Webhooks de dépôt

Notifications d'un payin, du moment où le transfert apparaît sur la chaîne jusqu'à ce que le montant soit disponible sur votre solde.

Paiements partiels

Un dépôt est marqué completed, et payment_detected / payment_confirmed sont envoyés, dès que received_amount atteint minimum_payment pour cent de crypto_amount. minimum_payment est défini par compte ; en dessous de 100, le client peut avoir payé moins que la facture. Avant de livrer, comparez data.received_amount à data.crypto_amount (tous deux en data.crypto_currency) et décidez quoi faire de la différence.

payment_detectedPaiement détecté

La transaction est apparue sur le réseau et le payin est terminé, mais ce n'est pas le statut final. funds_available vaut false et finality_status vaut pending_finality tant que le bloc peut encore être réorganisé. Si vous devez aller vite, vous pouvez livrer le produit sur cet avis. Le montant reste bloqué et ne fait pas partie du solde disponible tant que le réseau n'a pas atteint les confirmations requises.

Livrer le produit à cette étape est votre décision. Un retrait de ce montant est refusé jusqu'au payment_confirmed.

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_confirmedPaiement confirmé

Le bloc est définitif. funds_available vaut true et le montant est disponible sur votre solde. Créditez le client définitivement sur cet événement.

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_reversedPaiement annulé

Une réorganisation a défait le dépôt et le crédit a été retiré. data.status vaut reversed et reversal_reason en donne la raison. À partir de là, check-payin et list-payin renvoient aussi le statut reversed : une intégration qui interroge l'API le voit aussi. Si le produit avait déjà été livré sur payment_detected, rapprochez cette livraison de cet avis.

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"
}

Quand la détection est déjà définitive

Sur certains réseaux, le paiement est définitif dès sa détection. payment_confirmed est alors envoyé juste après payment_detected ; payment_detected porte déjà finality_status final, et payment_confirmed peut porter finality_status null. Décidez d'après event et funds_available : tous les payment_detected ne bloquent pas le montant.

Champs du dépôt

Champ	Type	Description
funds_available	boolean	false tant que le montant est bloqué. true quand il peut être retiré.
finality_status	string \| null	pending_finality pendant les confirmations, final quand le bloc est consolidé, reorged quand le dépôt a été annulé. Peut être null sur un payment_confirmed d'un paiement déjà définitif à la détection.
confirmations	number \| null	Réservé au nombre de confirmations. Actuellement toujours null ; ne vous y fiez pas.
estimated_release_seconds	number \| null	Réservé à l'estimation de l'attente avant libération. Actuellement toujours null ; ne vous y fiez pas.
reversal_reason	string \| null	Pourquoi le crédit a été retiré. Null sur payment_detected et payment_confirmed.
received_amount	string	Montant crypto crédité sur le reçu.
received_amount_fiat	string	Valeur fiat du montant reçu au cours de la facture.
received_amount_fiat_current	string	Valeur fiat au cours du moment où le webhook a été construit. Repli sur le cours de la facture si le prix en direct est indisponible.
cross_token	boolean	true lorsque le client a payé avec un jeton différent de celui de la facture.
paid_with	array	Jetons réellement reçus on-chain. Chaque élément a currency et amount.
is_wallet_fixed	boolean	true lorsque le dépôt est arrivé sur une adresse fixe.

is_duplicatedPayin Seulement

true quand Bifrost a créé ce payin lui-même, pour un paiement qui ne correspondait à aucun payin ouvert : un paiement supplémentaire vers une adresse dont le payin était déjà terminé, ou un paiement sur un autre réseau que celui de la facture. C'est un nouveau payin, avec son propre internal_reference et un reference_id généré par Bifrost. Le montant est crédité sur votre solde et l'avis est envoyé au webhook_url du payin d'origine.

Quand is_duplicated vaut true, le reference_id n'est pas le vôtre. Rattachez le paiement à votre commande par customer_info ou wallet. Le payin est aussi renvoyé par List Payins et Check Specific Payin.

customer_info

Votre propre identifiant du client, comme un ID utilisateur, un e-mail ou un numéro de commande. Il est renvoyé dans les webhooks et les listes, pour savoir à qui appartient chaque transaction, y compris les payins que Bifrost crée lui-même (paiements supplémentaires et dépôts sur adresse fixe), dont le reference_id est généré par Bifrost.