Pular para o conteúdo principal

Guia: criar cobrança (POST /orders)

Este fluxo é o equivalente conceitual ao criar um payin em gateways tradicionais: você registra uma intenção de pagamento e recebe os dados para o cliente concluir o pagamento.

Passo 1 — Obter credenciais​

Certifique-se de ter:

  • URL base da API: https://paychain-api.onrender.com (ou {{BASE_URL}} nos exemplos)
  • JWT válido (veja Autenticação)

Passo 2 — Definir o valor da ordem​

Você pode enviar o valor de uma das formas abaixo (não misture):

Opção A — Valor direto em stablecoin (USDT ou USDC)​

USDT (Solana):

{
  "network": "SOLANA",
  "token": "USDT",
  "amount": "100.00"
}
USDC — exemplo em destaque

Na Solana, use "token": "USDC" com o mesmo formato de amount. O backend precisa ter USDC_MINT_SOLANA configurado.

{
  "network": "SOLANA",
  "token": "USDC",
  "amount": "50.00"
}

Referência completa (BRL com USDC, cURLs): API — Ordens — POST /orders.

Opção B — Valor cotado em moeda fiduciária​

  • USD: paridade 1:1 com USDT (sem câmbio externo na prática).
  • BRL ou EUR: conversão usando feed público no servidor no momento da criação.
{
  "network": "SOLANA",
  "token": "USDT",
  "quoteCurrency": "BRL",
  "quoteAmount": "550.00"
}

A resposta incluirá o amount no token escolhido (USDT ou USDC) a pagar, além de quotedAt, fxRateLabel (ex.: 1 USDT = 5,32 BRL ou 1 USDC = …) e fxSource (open_fx, fixed ou legacy).

Cotação com USDC

Na opção B, defina também "token": "USDC" se quiser que a conversão BRL/EUR resulte em valor em USDC em vez de USDT.

Passo 3 — Chamar o endpoint de criação​

POST {{BASE_URL}}/orders

Headers:

Authorization: Bearer {{TOKEN}}
Content-Type: application/json

Passo 4 — Usar a resposta​

Em caso de sucesso, guarde pelo menos:

CampoUso
referenceIdentificador único da ordem nas próximas chamadas
payUrlLink para a página de pagamento do Paychain
qrDataDados para exibir QR (ex.: Solana Pay)
expiresAtPrazo para o cliente pagar

Opcional: webhookUrl no corpo da criação sobrescreve a URL padrão do perfil para esta ordem.

Passo 5 — Em caso de falha​

Se a requisição falhar (rede, validação, cotação indisponível para BRL/EUR):

  1. Corrija o payload ou tente novamente após instantes.
  2. Gere uma nova ordem se precisar de novo prazo ou valor — não reutilize reference de tentativas inválidas como se fossem a mesma cobrança.
Paralelo com checkout de cartão

Assim como em integrações onde is_checkout: true cria uma sessão e você redireciona ou embute o checkout, aqui a “sessão” é a ordem: o cliente completa o pagamento na carteira usando payUrl / QR, não um formulário de cartão na Paychain.

Referência cURL (todos os exemplos)​

API — Ordens — POST /orders (USDT e USDC, BRL/EUR), listagem, consulta, submit-tx, webhooks, Telegram e auditoria.

Próximo guia​

Fluxo de pagamento na Solana — do tx-request ao submit-tx e confirmação.