Webhooks de depósito

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_detectedPagamento 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_confirmedPagamento 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_reversedPagamento 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_duplicatedApenas 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.