Webhooks - Blockradar

Blockradar envoie des notifications webhook lorsqu’un ordre de paiement Deposit Fiat est créé ou atteint un état final. Configurez une URL de webhook sur le portefeuille utilisé pour créer l’ordre de paiement afin de recevoir ces événements.

Consultez le guide des webhooks pour la configuration des endpoints, la vérification des signatures, les nouvelles tentatives et le dépannage des livraisons.

Deux familles de webhooks

Deposit Fiat peut émettre deux familles de webhooks complémentaires :

Famille de webhooks	Représente	Identifiant
`onramp.payment-order.*`	La ressource ordre de paiement et ses instructions de paiement	`data.id` est l’ID de l’ordre de paiement
`onramp.*`	La transaction fiat vers crypto qui en résulte	`data.id` est l’ID de la transaction

Utilisez onramp.payment-order.* pour suivre la création de l’ordre et le statut du paiement. Utilisez onramp.* comme signal de transaction de référence pour le rapprochement et le règlement des actifs. Lorsqu’il est renseigné, le champ transactionId du payload de l’ordre de paiement relie l’ordre à la transaction ONRAMP correspondante. Les événements de transaction sont onramp.processing, onramp.success, onramp.failed et onramp.cancelled. Leur relation data.paymentOrder identifie l’ordre d’origine. Consultez Webhooks de transaction onramp pour le payload de référence et les recommandations de traitement.

Événements des ordres de paiement

`onramp.payment-order.created`

Envoyé après que Blockradar a créé avec succès l’ordre de paiement auprès du fournisseur sélectionné. Le payload contient les instructions de paiement que votre client utilise pour effectuer le virement fiat.

`onramp.payment-order.paid`

Envoyé lorsque Blockradar confirme que le paiement fiat a été reçu et que l’ordre de paiement a été réglé avec succès. Lorsqu’il est disponible, transactionId identifie la transaction Blockradar associée.

`onramp.payment-order.failed`

Envoyé lorsque l’ordre de paiement ne peut pas être finalisé. Récupérez l’ordre de paiement à l’aide de son id si vous avez besoin de la dernière réponse du fournisseur et des détails de l’échec.

`onramp.payment-order.cancelled`

Envoyé lorsque l’ordre de paiement est annulé avant un règlement réussi. Cela peut être déclenché par une demande d’annulation réussie ou par une mise à jour de statut du fournisseur.

Payload

Toutes les requêtes webhook des ordres de paiement utilisent l’enveloppe suivante :

{
  "event": "onramp.payment-order.paid",
  "data": {
    "id": "0198f028-7bb2-7000-8000-000000000001",
    "type": "onramp",
    "rail": "one_time_virtual_account",
    "reference": "deposit-order-001",
    "providerReference": "provider-order-001",
    "transactionId": "0198f02a-9201-7000-8000-000000000002",
    "status": "paid",
    "currency": "NGN",
    "amount": "100",
    "amountFiat": "150000",
    "feeFiat": "0",
    "amountFiatPayable": "150000",
    "amountFiatReceived": "150000",
    "amountSettled": "100",
    "expiresAt": "2026-08-01T13:00:00.000Z",
    "paymentInstructions": {
      "type": "one_time_virtual_account",
      "bank": {
        "name": "Example Bank",
        "code": null,
        "accountName": "Blockradar Payment",
        "accountNumber": "1234567890"
      },
      "expiresAt": "2026-08-01T13:00:00.000Z",
      "metadata": {
        "providerReference": "provider-order-001",
        "providerStatus": "settled",
        "currency": "NGN",
        "amountToTransfer": "150000",
        "targetAmount": "100"
      }
    },
    "metadata": {
      "orderId": "merchant-order-001"
    },
    "provider": {
      "id": "0198f020-0000-7000-8000-000000000003",
      "slug": "paycrest",
      "name": "Paycrest"
    },
    "wallet": {
      "id": "0198f020-0000-7000-8000-000000000004",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "address": null,
    "asset": {
      "id": "0198f020-0000-7000-8000-000000000005",
      "symbol": "USDC",
      "name": "USD Coin"
    },
    "customer": null,
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:10:00.000Z"
  }
}

La même structure data est utilisée pour chaque événement. Les champs qui ne sont pas disponibles à l’étape en cours peuvent être null. En particulier, transactionId, amountFiatReceived et amountSettled peuvent ne pas être renseignés dans l’événement onramp.payment-order.created.

Événement	`data.status` attendu	Signification
`onramp.payment-order.created`	`pending` ou `processing`	L’ordre de paiement a été créé et attend le paiement.
`onramp.payment-order.paid`	`paid`	Le paiement et le règlement ont été effectués avec succès.
`onramp.payment-order.failed`	`failed`	L’ordre de paiement n’a pas pu être finalisé.
`onramp.payment-order.cancelled`	`cancelled`	L’ordre de paiement a été annulé.

Traitement des événements

Renvoyez une réponse 2xx dès que l’événement est accepté.
Utilisez data.id comme identifiant de l’ordre de paiement et rendez le traitement idempotent.
Ne supposez pas que les événements arrivent une seule fois ou dans un ordre particulier.
Utilisez event et data.status ensemble pour mettre à jour l’ordre dans votre système.
Traitez onramp.payment-order.paid comme l’événement final de succès.
Traitez onramp.success comme l’événement final de succès pour la transaction onramp correspondante.

​Deux familles de webhooks

​Événements des ordres de paiement

​onramp.payment-order.created

​onramp.payment-order.paid

​onramp.payment-order.failed

​onramp.payment-order.cancelled

​Payload

​Traitement des événements

Deux familles de webhooks

Événements des ordres de paiement

`onramp.payment-order.created`

`onramp.payment-order.paid`

`onramp.payment-order.failed`

`onramp.payment-order.cancelled`

Payload

Traitement des événements