> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recevoir les mises a jour de statut des ordres de paiement Deposit Fiat.

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.

<Info>
  Consultez le [guide des webhooks](/fr/utilities/webhooks) pour la configuration
  des endpoints, la vérification des signatures, les nouvelles tentatives et le
  dépannage des livraisons.
</Info>

## 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](/fr/utilities/webhooks#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 :

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.