Webhooks

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.

See the Webhooks guide for endpoint configuration, signature verification, retries, and delivery troubleshooting.

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:

{
  "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.

API Documentation

Wallet

Addresses

Customer

Asset

Transactions

Withdraw

Withdraw Fiat

Signing

Swap

Liquidity Pool

Virtual Accounts

Deposit Fiat

Auto Settlements

Smart Contract

Gateway

Payment Links

AML

Asset Recovery

Miscellaneous

Rewards

Events

`onramp.payment-order.created`

`onramp.payment-order.paid`

`onramp.payment-order.failed`

`onramp.payment-order.cancelled`

Payload

Handling events

​Events

​onramp.payment-order.created

​onramp.payment-order.paid

​onramp.payment-order.failed

​onramp.payment-order.cancelled

​Payload

​Handling events

Events

`onramp.payment-order.created`

`onramp.payment-order.paid`

`onramp.payment-order.failed`

`onramp.payment-order.cancelled`

Payload

Handling events