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

> 接收法币入金支付订单的状态更新。

当法币入金支付订单被创建或进入终态时，Blockradar 会发送 webhook 通知。请在用于创建支付订单的钱包上配置 webhook URL，以接收这些事件。

<Info>
  有关端点配置、签名验证、重试以及投递故障排查，请参阅 [Webhooks 指南](/zh/utilities/webhooks)。
</Info>

## 两类 webhook

法币入金可以发送两类互补的 webhook：

| Webhook 类别 | 代表 | 标识符 |
| - | - | - |
| `onramp.payment-order.*` | 支付订单资源及其付款说明 | `data.id` 为支付订单 ID |
| `onramp.*` | 由此产生的法币到加密货币交易 | `data.id` 为交易 ID |

请使用 `onramp.payment-order.*` 跟踪订单创建和付款状态。请将 `onramp.*` 作为对账和资产结算的权威交易信号。当 `transactionId` 有值时，支付订单负载中的该字段会将订单关联到对应的 `ONRAMP` 交易。

交易事件包括 `onramp.processing`、`onramp.success`、`onramp.failed` 和 `onramp.cancelled`。其 `data.paymentOrder` 关联字段标识发起该交易的订单。有关权威负载和处理指南，请参阅[法币入金交易 webhooks](/zh/utilities/webhooks#法币入金交易-webhooks)。

## 支付订单事件

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

在 Blockradar 通过所选服务商成功创建支付订单后发送。负载中包含您的客户完成法币转账所需的付款说明。

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

在 Blockradar 确认已收到法币付款且支付订单已成功结算时发送。如有，`transactionId` 标识相关的 Blockradar 交易。

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

在支付订单无法完成时发送。如果您需要最新的服务商响应和失败详情，请使用其 `id` 获取该支付订单。

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

在支付订单于成功结算前被取消时发送。触发原因可能是取消请求成功，也可能是服务商的状态更新。

## 负载

所有支付订单 webhook 请求均使用以下结构：

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

每个事件都使用相同的 `data` 结构。当前阶段尚不可用的字段可能为 `null`。尤其是在 `onramp.payment-order.created` 事件中，`transactionId`、`amountFiatReceived` 和 `amountSettled` 可能尚未填充。

| 事件 | 预期的 `data.status` | 含义 |
| - | - | - |
| `onramp.payment-order.created` | `pending` 或 `processing` | 支付订单已创建，正在等待付款。 |
| `onramp.payment-order.paid` | `paid` | 付款和结算已成功完成。 |
| `onramp.payment-order.failed` | `failed` | 支付订单无法完成。 |
| `onramp.payment-order.cancelled` | `cancelled` | 支付订单已被取消。 |

## 处理事件

* 事件被接受后，请尽快返回成功的 `2xx` 响应。
* 使用 `data.id` 作为支付订单标识符，并确保处理具有幂等性。
* 不要假设事件只会到达一次或按特定顺序到达。
* 在您的系统中更新订单时，请同时使用 `event` 和 `data.status`。
* 将 `onramp.payment-order.paid` 视为成功的终态事件。
* 将 `onramp.success` 视为对应法币入金交易的成功终态事件。


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