# Receber um pagamento

> Versão em Markdown da documentação pública da API v1 da Bifrost Crypto, para agentes de IA e geradores de código. Mesmo conteúdo das páginas HTML, gerado da mesma fonte, sem navegação nem estilo.
>
> Versão HTML: https://bifrostcrypto.com/pt-BR/docs/guide-payin
> Arquivos relacionados: [ai.md](https://bifrostcrypto.com/ai/pt-BR.md) · [Postman](https://bifrostcrypto.com/postman-collection.json) · [OpenAPI](https://bifrostcrypto.com/openapi.json) · [llms.txt](https://bifrostcrypto.com/llms.txt)
> Outros idiomas: [English](https://bifrostcrypto.com/ai/en/guide-payin.md) · [Español](https://bifrostcrypto.com/ai/es/guide-payin.md) · [Français](https://bifrostcrypto.com/ai/fr/guide-payin.md)
> API v1 · contrato alterado pela última vez em 2026-10-10

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

## 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. 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. 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. 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. 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. 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. 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ção | O que fazer |
| --- | --- |
| Timeout ou sem resposta no POST /v1/payin | Reenvie 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=… |
| 400 | Corrija a requisição. Reenviar sem mudanças dá a mesma resposta. |
| 500, 502 ou 503 | Nada foi criado. Tente mais tarde com o mesmo reference_id. |
| 429 | Aguarde os segundos indicados em Retry-After. |
| O webhook não chegou | As 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.