# Webhooks de depósito

> 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/webhooks-receipts
> 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/webhooks-receipts.md) · [Español](https://bifrostcrypto.com/ai/es/webhooks-receipts.md) · [Français](https://bifrostcrypto.com/ai/fr/webhooks-receipts.md)
> API v1 · contrato alterado pela última vez em 2026-10-10

Notificações de um payin, do momento em que a transferência aparece na rede até o valor ficar disponível no seu saldo.

## Pagamentos parciais

Um depósito é marcado como completed, e payment_detected / payment_confirmed são enviados, quando received_amount atinge minimum_payment por cento de crypto_amount. O minimum_payment é definido por conta; abaixo de 100, o cliente pode ter pago menos que a fatura. Antes de entregar, compare data.received_amount com data.crypto_amount (ambos em data.crypto_currency) e decida o que fazer com a diferença.

## `payment_detected` · Pagamento detectado

A transação apareceu na rede e o payin está concluído, mas este não é o status final. funds_available é false e finality_status é pending_finality enquanto o bloco ainda pode ser reorganizado. Se precisar de agilidade, você pode liberar o produto neste aviso. O valor fica retido e não faz parte do saldo disponível até a rede atingir as confirmações exigidas.

> Liberar o produto nesta etapa é uma decisão sua. Um saque desse valor é recusado até o payment_confirmed. Até hoje nenhum pagamento detectado pela Bifrost foi revertido; veja payment_reversed.

```json
{
  "data": {
    "status": "success",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "pending_finality",
    "funds_available": false,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": null,
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_detected",
  "timestamp": "2026-03-01 12:02:00"
}
```

## `payment_confirmed` · Pagamento confirmado

O bloco é final. funds_available é true e o valor está disponível no seu saldo. Credite o cliente de forma definitiva neste evento.

```json
{
  "data": {
    "status": "success",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "final",
    "funds_available": true,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": null,
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_confirmed",
  "timestamp": "2026-03-01 12:03:00"
}
```

## `payment_reversed` · Pagamento revertido

Pode ficar tranquilo: até hoje nenhum pagamento recebido pela Bifrost foi revertido.

Este aviso existe só por causa das redes L2, como Arbitrum, Optimism e Base. Nelas, o pagamento é detectado assim que entra num bloco da L2 (payment_detected), em segundos, e se torna definitivo quando esse bloco é finalizado na rede principal (payment_confirmed), alguns minutos depois. Em teoria, uma transação pode ser desfeita nesse intervalo. É raríssimo, mas como a possibilidade existe, preferimos documentar.

Se acontecer, o crédito daquele depósito é retirado do saldo, data.status vem como reversed e reversal_reason informa o motivo. A partir daí, check-payin e list-payin também devolvem status reversed.

Se você libera o produto só em payment_confirmed, este aviso não afeta você. Se libera em payment_detected, basta ligar este aviso ao pedido pelo internal_reference.

```json
{
  "data": {
    "status": "reversed",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "reorged",
    "funds_available": false,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": "reorg",
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_reversed",
  "timestamp": "2026-03-01 12:04:00"
}
```

## Quando a detecção já é final

Em algumas redes o pagamento é final assim que é detectado. O payment_confirmed é enviado logo depois do payment_detected; o payment_detected já traz finality_status final, e o payment_confirmed pode trazer finality_status null. Decida pelo event e pelo funds_available: nem todo payment_detected retém o valor.

## Campos do depósito

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `funds_available` | `boolean` | false enquanto o valor está retido. true quando pode ser sacado. |
| `finality_status` | `string \| null` | pending_finality enquanto as confirmações correm, final quando o bloco está consolidado, reorged quando o depósito foi desfeito. Pode ser null num payment_confirmed de pagamento que já era final na detecção. |
| `confirmations` | `number \| null` | Reservado para a contagem de confirmações. Hoje vem sempre null; não dependa dele. |
| `estimated_release_seconds` | `number \| null` | Reservado para a estimativa de espera até a liberação. Hoje vem sempre null; não dependa dele. |
| `reversal_reason` | `string \| null` | Por que o crédito foi retirado. Null em payment_detected e payment_confirmed. |
| `received_amount` | `string` | Valor em cripto creditado no recibo. |
| `received_amount_fiat` | `string` | Valor fiat do montante recebido na cotação da invoice. |
| `received_amount_fiat_current` | `string` | Valor fiat na cotação do momento em que o webhook foi montado. Cai para a cotação da invoice se o preço ao vivo não estiver disponível. |
| `cross_token` | `boolean` | true quando o cliente pagou em um token diferente do token da invoice. |
| `paid_with` | `array` | Tokens de fato recebidos on-chain. Cada item tem currency e amount. |
| `is_wallet_fixed` | `boolean` | true quando o depósito caiu em um endereço fixo. |

**`is_duplicated`** (Apenas Payin)

true quando a própria Bifrost criou este payin, para um pagamento que não correspondia a um payin em aberto: um pagamento extra para um endereço cujo payin já estava concluído, ou um pagamento em rede diferente da fatura. É um payin novo, com internal_reference próprio e reference_id gerado pela Bifrost. O valor é creditado no seu saldo e o aviso vai para o webhook_url do payin original.

> Quando is_duplicated é true, o reference_id não é seu. Vincule o pagamento ao seu pedido por customer_info ou wallet. O payin também aparece em List Payins e Check Specific Payin.

**`customer_info`**

Seu próprio identificador do cliente, como ID de usuário, e-mail ou número do pedido. Ele volta nos webhooks e nas listagens, então você sabe de quem é cada transação, inclusive os payins que a Bifrost cria por conta própria (pagamentos adicionais e depósitos em endereço fixo), cujo reference_id é gerado pela Bifrost.