Pular para o conteúdo principal

Guia: fluxo de pagamento na Solana

Este guia descreve o que acontece depois que você criou a ordem e entregou payUrl ou QR ao cliente — análogo ao fluxo em que o usuário preenche checkout e confirma, aqui com carteira e rede Solana.

Passo 1 — Cliente abre o link ou escaneia o QR​

A página de pagamento (pública) identifica a ordem pelo reference e apresenta instruções para conectar a carteira (ex.: Phantom).

Passo 2 — Obter a transação para assinatura​

O frontend da Paychain (ou sua integração, se usar APIs diretas) chama:

GET /pay/tx-request/:reference?account=<PAYER_PUBKEY>

  • account: chave pública Solana de quem vai pagar.
  • Resposta: transação serializada (ex.: base64) e metadados para a carteira assinar.

Isso corresponde, em espírito, ao “exibir o checkout” onde o adquirente monta a transação que o usuário autorizará.

Passo 3 — Assinatura e envio na rede​

  1. A carteira exibe o valor, token (USDT) e destinos.
  2. O usuário aprova; a carteira assina e envia a transação à Solana.
  3. Após o envio, obtém-se o identificador da transação (signature / txId).

Passo 4 — Registrar o txId na Paychain​

Chamada pública (fluxo página de pagamento):

POST /pay/:reference/submit-tx

{
  "txId": "assinatura_da_transacao_na_solana"
}

Integrações server-side também podem usar a rota autenticada POST /orders/:reference/submit-tx quando aplicável.

Passo 5 — Confirmação e status​

O backend/worker confirma a transação na rede e atualiza o status da ordem (ex.: paga / sucesso). Você recebe webhook (se configurado) e pode consultar GET /orders/:reference para o estado atual.

Passo 6 — Autenticação forte (paralelo com 3DS)​

Em cartão, débito pode exigir 3DS. Na blockchain, a “prova forte” é a própria assinatura na carteira: o usuário confirma no app da wallet — não há etapa 3DS da adquirência, mas o efeito é semelhante (confirmação explícita do titular).

Falhas comuns​

  • Saldo ou ATA insuficiente → transação falha na rede; ordem não vai a “paga” até haver confirmação válida.
  • Prazo expirado → ordem pode ir para estado expirado; crie nova ordem se necessário.

Próximo guia​

Webhooks e auditoria