> ## 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

> Receive status updates for Deposit Fiat payment orders.

Blockradar sends webhook notifications when a Deposit Fiat payment order is
created or reaches a terminal state. Configure a webhook URL on the wallet used
to create the payment order to receive these events.

<Info>
  See the [Webhooks guide](/en/utilities/webhooks) for endpoint configuration,
  signature verification, retries, and delivery troubleshooting.
</Info>

## Events

### `onramp.payment-order.created`

Sent after Blockradar successfully creates the payment order with the selected
provider. The payload contains the payment instructions your customer uses to
complete the fiat transfer.

### `onramp.payment-order.paid`

Sent when Blockradar confirms that the fiat payment was received and the payment
order was settled successfully. When available, `transactionId` identifies the
related Blockradar transaction.

### `onramp.payment-order.failed`

Sent when the payment order cannot be completed. Fetch the payment order using
its `id` if you need the latest provider response and failure details.

### `onramp.payment-order.cancelled`

Sent when the payment order is cancelled before successful settlement. This can
be triggered by a successful cancellation request or by a provider status
update.

## Payload

All payment-order webhook requests use the following envelope:

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

The same `data` shape is used for every event. Fields that are not available at
the current stage can be `null`. In particular, `transactionId`,
`amountFiatReceived`, and `amountSettled` might not be populated on the
`onramp.payment-order.created` event.

| Event                            | Expected `data.status`    | Meaning                                                |
| -------------------------------- | ------------------------- | ------------------------------------------------------ |
| `onramp.payment-order.created`   | `pending` or `processing` | The payment order was created and is awaiting payment. |
| `onramp.payment-order.paid`      | `paid`                    | Payment and settlement completed successfully.         |
| `onramp.payment-order.failed`    | `failed`                  | The payment order could not be completed.              |
| `onramp.payment-order.cancelled` | `cancelled`               | The payment order was cancelled.                       |

## Handling events

* Return a successful `2xx` response as soon as the event is accepted.
* Use `data.id` as the payment-order identifier and make processing idempotent.
* Do not assume events arrive only once or in a particular order.
* Use `event` and `data.status` together when updating the order in your system.
* Treat `onramp.payment-order.paid` as the successful terminal event.