API de pagamentos

A API de pagamentos permite criar sessões de pagamento, redirecionar clientes para um checkout hospedado e acompanhar o status do pagamento.

Criar pagamento

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Checkout hospedado, H2H e valores exatos de criptomoeda

O mesmo endpoint suporta três formatos distintos de fatura. Escolha um deliberadamente; não misture a semântica de seus valores.

Checkout hospedado com opção de pagador

Envie amount, currency, order_id e url_callback, mas omita to_currency e network. A resposta contém result.url; address, qr e às vezes campos do pagador permanecem null até que o pagador selecione uma direção na página hospedada.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Fatura H2H de endereço direto

Envie ambos to_currency e network. 2328.io cria a fatura blockchain durante a chamada da API, portanto, uma resposta bem-sucedida pode ser exibida dentro do seu checkout sem redirecionar o cliente.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Exiba esses valores exatamente como retornados:

• payer_amount e payer_currency — a instrução de pagamento;
• network e address — o único destino para esta fatura;
• qr — um URI de dados para o mesmo endereço;
• expires_at — o prazo da fatura;
• url — um fallback hospedado útil quando o checkout personalizado não pode ser concluído.

Fatura por uma quantidade exata de criptomoeda

Coloque a criptomoeda em currency quando a própria fatura estiver denominada em criptomoeda:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

O valor solicitado da criptomoeda é preservado em payer_currency / payer_amount. O serviço também pode manter uma avaliação em USD internamente para campos contábeis e de taxa; não substitua a instrução exata de criptomoeda por essa avaliação. Preserve as strings decimais retornadas, incluindo a precisão final.

Para uma criptomoeda com apenas uma rede suportada, a rede pode ser selecionada automaticamente. Ainda é recomendado fornecer network explicitamente para uma integração determinística. Para ativos de múltiplas redes, como stablecoins, sempre envie.

Idempotência e tentativas de nova tentativa

order_id está vinculado ao projeto do comerciante autenticado e funciona como a chave de idempotência de criação. Se um pagamento já existir, a API retorna essa sessão com state: 0.

Algoritmo de criação recomendado:

1. Insira sua tentativa de pagamento local e order_id único em uma transação de banco de dados.
2. Envie a requisição de API assinada.
3. Persista o uuid retornado e a resposta completa.
4. Se o resultado HTTP for perdido, tente novamente a mesma requisição ou consulte /v1/payment/info via order_id.
5. Nunca crie um segundo pedido local apenas porque a requisição upstream expirou.

Casos extremos de pagamento

A URL de retorno do navegador é apenas para navegação. Um cliente pode abri-la sem pagar, fechá-la após pagar ou reproduzi-la mais tarde. Apenas um estado de API/webhook verificado pode liquidar o pedido do comerciante.

Informações do pagamento

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Lista de pagamentos

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"