Integração de checkout em USDC

A estrutura padrão da API

As APIs de aceitação de pagamentos em USDC seguem, em termos gerais, o padrão de intenção de pagamento popularizado pela Stripe. A superfície mínima:

1. 1

   O servidor cria a intenção de pagamento

   POST /v1/payments com um corpo que contém amount, currency (USD se a cotação for em moeda fiduciária; USDC se for em stablecoin), settlement_preference (USDC ou moeda fiduciária), networks (lista de redes permitidas), order_id (a sua chave de idempotência), success_url, cancel_url e um bloco metadata para a sua própria reconciliação.

2. 2

   O adquirente devolve o URL de checkout ou a configuração do widget

   No checkout alojado: um URL para o qual o comprador é redirecionado. No widget incorporado: uma configuração do lado do cliente (chave publicável, ID da intenção) que o widget carrega. Ambos os fluxos tratam da deteção da carteira, da escolha da rede e da apresentação da cotação.

3. 3

   O comprador assina na carteira e a transferência on-chain é difundida

   Telemóvel: ligação direta (deep link) para a MetaMask, a Phantom, a Trust, etc. Computador: código QR da WalletConnect ou janela da extensão do navegador. O comprador verifica o montante e assina.

4. 4

   O adquirente aguarda as confirmações e dispara o webhook

   POST your_webhook_url com um payload que contém event_type: “payment.succeeded”, order_id, amount, tx_hash, network e uma assinatura que verifica com o segredo de webhook do adquirente.

5. 5

   O servidor marca a encomenda como paga de forma idempotente

   Verifique a assinatura do webhook, procure (order_id, tx_hash) na sua base de dados, marque como paga se ainda não estiver marcada e despache a encomenda.

Escolha da rede

A escolha das redes a aceitar é um compromisso entre experiência de utilização e custo:

• Solana: comissão de rede inferior a um cêntimo, confirmação em menos de um segundo. A melhor opção predefinida para um valor médio de encomenda (AOV) baixo.
• Base: comissão de rede de alguns cêntimos, confirmação em alguns segundos. Bom suporte por parte das carteiras; boa opção predefinida para públicos familiarizados com cripto.
• Polygon, Arbitrum: comissões e velocidade semelhantes às da Base. Podem ser acrescentadas, mas não são estritamente necessárias.
• Mainnet da Ethereum: comissão de rede de $1–$8+, consoante o gas. Penosa para os compradores em encomendas pequenas. Aceite-a para um AOV elevado (acima de $500) ou como alternativa.
• Tron: se o seu alvo são fluxos de USDT na Ásia/África, vale a pena considerar suportar USDT-TRON a par de USDC.

Idempotência dos webhooks

Os webhooks são reenviados. O seu handler tem de ser idempotente. O padrão habitual:

1. Verifique a assinatura do webhook com HMAC-SHA256, usando o segredo do seu adquirente.
2. Extraia (order_id, tx_hash) do payload.
3. Procure esse par na sua tabela processed_payments.
4. Se o encontrar: devolva 200 OK sem fazer mais nada.
5. Se não o encontrar: insira a linha (com uma restrição UNIQUE sobre o par), depois marque a encomenda como paga na sua tabela principal de encomendas e, por fim, despache a encomenda.
6. Envolva os passos 5 numa única transação da base de dados, para que uma falha a meio do fluxo não resulte num despacho em duplicado.

A maioria dos webhooks de aceitação de pagamentos inclui um ID de entrega; registe-o para efeitos de depuração, mas não o use como chave de idempotência. As confirmações da rede e os reenvios do adquirente podem gerar eventos payment.succeeded duplicados, com IDs de entrega diferentes mas o mesmo tx_hash; a sua desduplicação tem de assentar na identidade on-chain, e não na entrega.

Fluxo de reembolso

Predominam dois padrões:

• Reembolso ao remetente: o adquirente devolve os USDC para o endereço a partir do qual o comprador pagou originalmente. É a experiência mais simples; funciona porque o registo on-chain do pagamento contém o endereço de origem.
• Reembolso para um endereço indicado: o comprador indica um destino para o reembolso (que pode ser diferente da origem, se tiver pago a partir de uma exchange ou de uma hot wallet). A maioria dos adquirentes suporta-o através de um POST /v1/refunds com destination_address.

O comerciante paga a comissão de rede na etapa do reembolso. São suportados tanto reembolsos totais como parciais. O reembolso em si demora o mesmo tempo de confirmação on-chain que o pagamento original.

Modos de falha em produção

• O comprador desiste depois de assinar. A transferência on-chain é difundida, mas o comprador fecha o separador antes de o webhook ser disparado. O adquirente continua a detetar e a confirmar o pagamento através da monitorização on-chain; o seu despacho é acionado pelo webhook, e não pelo redirecionamento.
• O comprador paga o montante errado. A maioria dos adquirentes rejeita montantes divergentes no momento da deteção on-chain. Alguns aceitam correspondências aproximadas (dentro de uma tolerância) e assinalam a discrepância no webhook.
• O comprador paga na rede errada. Se assinar na Ethereum mas a sua loja só aceitar Solana, o pagamento escapa por completo à monitorização do seu adquirente. A maioria dos fornecedores devolve os fundos através de um processo de recuperação; alguns perdem-nos. Torne a escolha da rede clara no checkout.
• O comprador paga a partir de um endereço de exchange. Os reembolsos para a origem podem ser devolvidos ou chegar à conta errada. Recolha explicitamente um endereço de destino para reembolsos no checkout de qualquer produto em que os reembolsos sejam prováveis.
• Perda de paridade da stablecoin (depeg). Rara, mas real. Se a USDC perder significativamente a paridade durante o breve intervalo entre a cotação e a liquidação on-chain, é o comerciante ou o adquirente que absorve a diferença, consoante o acordo.