Receber um pagamento

Da escolha do token à entrega do pedido, usando payins criados pela API.

  1. 1

    Escolha o token e a rede

    GET /v1/summary/tokens lista os tokens da plataforma por rede, com min_receipt e max_receipt. A lista não é filtrada pela sua conta: a criação do payin confirma se o token aceita depósito para você naquela rede.

    bash
    curl "https://bridge.bifrostcrypto.com/v1/summary/tokens" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY"
  2. 2

    Crie o payin

    POST /v1/payin com um reference_id único no seu sistema, o valor (process_by crypto_amount ou fiat_amount), o webhook_url e, se quiser, expires_at em segundos (padrão de 4 horas). Guarde o internal_reference da resposta e mostre ao cliente a wallet, e o memo quando o token exigir.

    bash
    curl -X POST "https://bridge.bifrostcrypto.com/v1/payin" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference_id":"order_1001","crypto_currency":"USDT","network":"BinanceSmartChain","process_by":"crypto_amount","crypto_amount":"50","webhook_url":"https://your-site.com/webhook","customer_info":"customer_42"}'
  3. 3

    Receba o webhook

    Verifique o X-Bifrost-Signature sobre o corpo bruto, responda 2xx em até 30 segundos e processe depois. O mesmo aviso pode chegar mais de uma vez: elimine duplicatas por data.internal_reference junto com event.

  4. 4

    Confira o valor antes de entregar

    O payin fica concluído quando received_amount atinge minimum_payment por cento de crypto_amount, o que pode ser menos que o valor total. Compare data.received_amount com data.crypto_amount e decida o que fazer com a diferença.

  5. 5

    Escolha quando entregar

    payment_detected significa que a transferência foi vista (funds_available false): entregar agora é decisão sua e traz o risco de reversão. payment_confirmed significa que é final (funds_available true).

  6. 6

    Trate as exceções

    payment_reversed: a rede desfez o pagamento e o crédito foi retirado; o check-payin passa a devolver status reversed. is_duplicated true: um pagamento extra ou em outra rede gerou um payin novo, com referências próprias; vincule ao pedido por customer_info.

  7. 7

    Concilie

    GET /v1/check-payin/{internal_reference} devolve o payin a qualquer momento. GET /v1/statements lista as movimentações do saldo: DEPOSIT para o crédito, RATE e FEE para as cobranças.

O que fazer quando algo falha

POST /v1/payin não tem Idempotency-Key. O reference_id é o que impede um segundo payin.

SituaçãoO que fazer
Timeout ou sem resposta no POST /v1/payinReenvie com o mesmo reference_id. Se a resposta for duplicate_reference_id, a primeira requisição funcionou: busque-a com GET /v1/list-payin?reference_id=…
400Corrija a requisição. Reenviar sem mudanças dá a mesma resposta.
500, 502 ou 503Nada foi criado. Tente mais tarde com o mesmo reference_id.
429Aguarde os segundos indicados em Retry-After.
O webhook não chegouAs entregas são repetidas até 10 vezes, com cerca de 5 minutos entre elas. Enquanto isso, consulte o payin com GET /v1/check-payin/{internal_reference}.

Payins criados no painel não são devolvidos pela API.