PaymentButton

O componente PaymentButton é um componente React que fornece uma interface completa de pagamento para aceitar pagamentos Solana. Ele gerencia internamente a conexão da carteira, seleção de tokens, processamento de transações e gerenciamento de estado da interface. Por padrão, vem com botão e modais personalizáveis:

Botão de Gorjeta

Botão de Gorjeta

Modal de Pagamento

Modal de Pagamento

Modal do Código QR Solana Pay

Modal do Carrinho

Instalação

pnpm add @solana-commerce/kit

Props do Componente

PaymentButtonProps

O componente PaymentButton aceita as seguintes props:

Props Obrigatórias

• config (SolanaCommerceConfig) - Objeto de configuração principal para o componente de pagamento. Esta é a única prop obrigatória. Consulte SolanaCommerceConfig abaixo.

Props Opcionais

• paymentConfig (PaymentConfig) - Configuração específica do pagamento incluindo produtos, substituições de preços e buscadores de preços personalizados. Consulte PaymentConfig abaixo.

• onPayment ((amount: number, currency: string) => void) - Chamado quando um pagamento é iniciado após o usuário confirmar o valor e a moeda. Recebe o valor do pagamento (em unidades de token, não lamports) e o identificador da moeda.

• onPaymentStart (() => void) - Chamado quando o fluxo de pagamento começa, antes da transação real ser enviada. Use isto para mostrar estados de carregamento ou rastreamento de analytics.

• onPaymentSuccess ((signature: string) => void) - Chamado quando a transação é confirmada na blockchain. Recebe a assinatura da transação. É aqui que você deve atualizar o status do pedido, enviar e-mails de confirmação, etc.

• onPaymentError ((error: Error) => void) - Chamado quando o pagamento falha em qualquer etapa (conexão da carteira, envio da transação ou confirmação). O objeto de erro contém detalhes sobre o que deu errado.

• onCancel (() => void) - Chamado quando o usuário explicitamente cancela o fluxo de pagamento (fecha o modal ou clica em cancelar).

• children (React.ReactNode) - Elemento acionador personalizado opcional. Se fornecido, substitui o botão de pagamento padrão. O elemento filho deve ser clicável (por exemplo, um botão).

• className (string) - Nome da classe CSS aplicada ao botão acionador (usado apenas quando nenhum filho personalizado é fornecido).

• style (React.CSSProperties) - Estilos inline aplicados ao botão acionador (usado apenas quando nenhum filho personalizado é fornecido).

• variant ('default' | 'icon-only') - Variante do botão. O padrão mostra texto e ícone, 'icon-only' mostra apenas o ícone de pagamento.

Objetos de Configuração

SolanaCommerceConfig

O objeto de configuração principal passado para a prop config.

Campos Obrigatórios

• merchant (MerchantConfig) - Informações do comerciante e detalhes do destinatário do pagamento. Consulte MerchantConfig.

• mode ('cart' | 'tip' | 'buyNow') - Modo de pagamento que determina o texto exibido no botão e o fluxo da interface:

  • 'buyNow' - Compra de produto único com valor fixo
  • 'cart' - Carrinho de compras com múltiplos produtos
  • 'tip' - O usuário escolhe seu próprio valor (doações/gorjetas)

Campos Opcionais

• position ('inline' | 'overlay') - Como a interface de pagamento é exibida. O padrão é 'overlay'.

  • 'overlay' - Abre em uma sobreposição modal/drawer
  • 'inline' - Incorporado diretamente na página

• theme (ThemeConfig) - Opções de personalização visual. Consulte ThemeConfig.

• network ('mainnet' | 'devnet' | 'testnet') - Rede Solana a ser usada. O padrão é 'mainnet'.

• rpcUrl (string) - URL do endpoint RPC personalizado. Se não fornecido, usa um endpoint público padrão para a rede selecionada.

• allowedMints (string[]) - Array de endereços de mint de tokens para restringir métodos de pagamento. Se não fornecido, todos os tokens suportados (SOL, USDC, USDT) estão disponíveis.

• showQR (boolean) - Se deve mostrar a opção de pagamento por código QR. Útil para dispositivos móveis e integração com Solana Pay.

• enableWalletConnect (boolean) - Se deve habilitar a conexão de carteira. Defina como false se estiver gerenciando a conexão de carteira externamente.

• showMerchantInfo (boolean) - Se deve exibir o nome e o logotipo do comerciante na interface de pagamento.

• debug (boolean) - Ativa o registro detalhado no console para depuração.

MerchantConfig

Define o destinatário do pagamento e as informações do negócio.

Campos Obrigatórios

• name (string) - Nome da empresa ou comerciante exibido aos usuários durante o checkout.

• wallet (string) - Endereço da carteira Solana que receberá os pagamentos. Deve ser um endereço Solana válido codificado em base58.

Campos Opcionais

• logo (string) - URL da imagem do logotipo do comerciante. Exibido na interface de pagamento quando showMerchantInfo está habilitado.

• description (string) - Descrição do negócio mostrada aos usuários.

ThemeConfig

Personalização visual para a interface de pagamento.

Todos os campos são opcionais e possuem valores padrão sensatos.

• primaryColor (string) - Cor principal da marca usada para botões e destaques. Padrão: '#9945FF' (roxo Solana).

• secondaryColor (string) - Cor de destaque secundária. Padrão: '#14F195' (verde Solana).

• backgroundColor (string) - Cor de fundo do modal/contêiner. Padrão: '#ffffff'.

• textColor (string) - Cor do texto principal. Padrão: '#111827'.

• borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - Raio da borda aplicado aos elementos da interface. Padrão: 'lg'.

  • 'none' = 0px
  • 'sm' = 12px
  • 'md' = 16px
  • 'lg' = 20px
  • 'xl' = 24px
  • 'full' = Totalmente arredondado (dependente do contexto)

• fontFamily (string) - Família de fontes para todo o texto. Padrão: 'system-ui, -apple-system, sans-serif'.

• buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - Sombra projetada para botões. Padrão: 'md'.

• buttonBorder ('none' | 'black-10') - Estilo de borda para botões. Padrão: 'black-10' (borda preta sutil).

PaymentConfig

Configuração avançada de pagamento para preços, decimais e produtos.

Todos os campos são opcionais.

• products (Product[]) - Array de produtos para os modos 'cart' ou 'buyNow'. Obrigatório ao usar esses modos. Cada produto tem:

  • id (string, obrigatório) - Identificador único do produto
  • name (string, obrigatório) - Nome do produto exibido ao usuário
  • quantity (number, obrigatório) - Quantidade deste produto
  • price (number, opcional) - Preço por unidade em USD
  • unitAmount (number, opcional) - Alternativa ao campo price
  • description (string, opcional) - Descrição do produto

• solPriceUsd (number) - Preço fixo de SOL em USD. Use isso para testes ou quando quiser fixar o preço do SOL. Se não fornecido, o componente obtém o preço atual do CoinGecko.

• getSolPrice (() => Promise<number>) - Função personalizada para obter o preço do SOL. Use isso para:

  • Oráculos de preço privados
  • Evitar limites de taxa de APIs públicas
  • Lógica de preços personalizada
  • Aplicações empresariais

  Se não fornecido, utiliza por padrão a API pública do CoinGecko com cache de 1 minuto.

• tokenDecimals ({ [currency: string]: number }) - Sobrescrever a precisão decimal do token. Útil para tokens personalizados. Exemplo:

  tokenDecimals: {
    'CUSTOM': 8,
    'USDC': 6  // Can override defaults
  }

• fallbackSolPriceUsd (number) - Preço de fallback do SOL se a API de preços falhar e nenhum cache estiver disponível. Sem isso, a interface de pagamento mostrará um erro se a obtenção do preço falhar.

Hooks Internos

O componente PaymentButton usa vários hooks internos para gerenciar estado e calcular valores:

useTheme(theme?: ThemeConfig)

Mescla a configuração de tema fornecida pelo usuário com os valores de tema padrão. Retorna um objeto ThemeConfig completo com todos os campos preenchidos.

Valores de tema padrão:

• primaryColor: '#9945FF'
• secondaryColor: '#14F195'
• backgroundColor: '#ffffff'
• textColor: '#111827'
• borderRadius: 'lg'
• fontFamily: 'system-ui, -apple-system, sans-serif'
• buttonShadow: 'md'
• buttonBorder: 'black-10'

O hook é memoizado e só recalcula quando a configuração do tema muda.

useTotalAmount(mode, paymentConfig?)

Calcula o valor total do pagamento com base no modo de comércio e produtos.

Comportamento por modo:

• Modo 'tip' - Retorna 0 (o valor é determinado pelo usuário)
• Modos 'cart' e 'buyNow' - Soma price * quantity para todos os produtos em paymentConfig.products

O hook trata casos extremos:

• Preços ausentes ou inválidos assumem o padrão 0
• Quantidades ausentes ou inválidas assumem o padrão 0
• Garante que todos os valores sejam números finitos
• Suporta tanto os campos de produto price quanto unitAmount

Retorna o valor total como um número (em USD para carrinho/compra imediata, 0 para gorjeta).

usePaymentUrl(merchant, amount, mode)

Gera uma URL Solana Pay para o pagamento. Esta URL pode ser codificada como um código QR para leitura por carteiras móveis.

Retorna: Uma URL de protocolo solana: com parâmetros de consulta para:

• recipient - Endereço da carteira do comerciante
• amount - Valor do pagamento
• reference - Referência de pagamento única (gerada a partir de timestamp + string aleatória)
• label - Nome do comerciante (sanitizado para segurança de URL)
• message - Mensagem contextual baseada no modo

Retorna uma string vazia se a carteira do comerciante for inválida ou o valor for <= 0.

Segurança: O nome do comerciante é sanitizado usando sanitizeString() para prevenir ataques XSS através de injeção de URL.

Validação e Tratamento de Erros

O componente realiza validação antes da renderização:

1. Validação de Carteira - Usa isAddress() de gill para validar o endereço da carteira do comerciante. Se inválido, renderiza um estado de erro em vez da interface de pagamento.

2. Validação de Preços - Garante que a precificação configurada seja válida:

   • Para o modo 'tip': Sempre válido (o usuário escolhe o valor)
   • Para os modos 'cart' e 'buyNow': Valida que totalAmount > 0

3. Segurança SSR - Usa detecção no lado do cliente para evitar incompatibilidades de hidratação. O estado isClient garante que recursos exclusivos do navegador (como localStorage para persistência de carteira) sejam executados apenas no cliente.

Arquitetura de Componentes

O PaymentButton envolve todos os elementos filhos em dois provedores de contexto:

1. AppProvider - Fornece o estado de conexão da carteira e o cliente do conector

   • Conexão automática: desativada por padrão
   • Armazenamento: Usa localStorage quando disponível (apenas no lado do cliente)
   • Modo de depuração: configurável através da configuração

2. ArcProvider - Fornece o cliente da blockchain Solana e a conexão RPC

   • Rede: Determinada a partir de config.network
   • URL RPC: Usa resolução no lado do servidor com fallback para endpoints públicos

Resolução de URL RPC

O componente inclui resolução sofisticada de URL RPC:

• Se config.rpcUrl for fornecido, ele é usado diretamente
• Caso contrário, chama um resolvedor no lado do servidor que seleciona endpoints confiáveis
• Reverte para https://api.mainnet-beta.solana.com se a resolução falhar
• A resolução acontece de forma assíncrona na montagem e atualiza o estado

Modos de Renderização

Modo sobreposição (position: 'overlay' ou padrão):

• Renderiza um botão de acionamento (personalizado ou padrão)
• Abre a interface de pagamento em um modal responsivo (desktop) ou gaveta (mobile)
• Usa o componente ResponsiveShell para layouts adaptativos

Modo inline (position: 'inline'):

• Incorpora a interface de pagamento diretamente na página
• Nenhum botão de acionamento necessário
• Útil para páginas de checkout dedicadas

Ambos os modos usam SecureIframeShell internamente para renderizar a interface de pagamento em um iframe isolado para segurança.

Exemplos de Uso

Pagamento Básico

<PaymentButton
  config={{
    merchant: {
      name: "Coffee Shop",
      wallet: "your-wallet-address"
    },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [
      {
        id: "coffee-001",
        name: "Espresso",
        price: 4.5,
        quantity: 1
      }
    ]
  }}
  onPaymentSuccess={(sig) => {
    console.log("Payment confirmed:", sig);
  }}
/>

Widget de Gorjeta com Buscador de Preço Personalizado

<PaymentButton
  config={{
    merchant: {
      name: "Content Creator",
      wallet: "creator-wallet"
    },
    mode: "tip"
  }}
  paymentConfig={{
    // Use your own price API to avoid rate limits
    getSolPrice: async () => {
      const res = await fetch("/custom-api/solana-price");
      const data = await res.json();
      return data.price;
    },
    // Fallback if your API fails
    fallbackSolPriceUsd: 200
  }}
/>

Carrinho de Compras com Tema Personalizado

<PaymentButton
  config={{
    merchant: {
      name: "My Store",
      wallet: "store-wallet",
      logo: "/logo.png"
    },
    mode: "cart",
    theme: {
      primaryColor: "#FF6B6B",
      backgroundColor: "#1a1a1a",
      textColor: "#ffffff",
      borderRadius: "xl",
      buttonShadow: "lg"
    },
    showMerchantInfo: true
  }}
  paymentConfig={{
    products: [
      { id: "1", name: "T-Shirt", price: 25, quantity: 2 },
      { id: "2", name: "Hoodie", price: 45, quantity: 1 }
    ]
  }}
  onPaymentSuccess={(signature) => {
    // Verify transaction on your backend
    fetch("/api/verify-payment", {
      method: "POST",
      body: JSON.stringify({ signature })
    });
  }}
/>

Botão de Acionamento Personalizado

<PaymentButton
  config={{
    merchant: { name: "Shop", wallet: "address" },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [{ id: "1", name: "Product", price: 10, quantity: 1 }]
  }}
>
  <button className="custom-button">🚀 Pay with Solana</button>
</PaymentButton>