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

# 订单事件

> 当法币兑加密货币或加密货币兑法币订单状态发生变化时，VelaFi 发送到您端点的 ORDER_WEBHOOK 事件负载参考。

当通过 API 创建的法币/加密货币订单进入以下任一状态时，VelaFi 会向您注册的 `ORDER_WEBHOOK` 端点发送一个已签名的 HTTP POST 请求。非通过 API 创建的订单不会触发此 Webhook。负载包含完整的订单快照，包括金额、价格以及更新后的状态码。您的端点必须验证 `signature` 请求头，并返回 `{"callbackStatus": "SUCCESS"}` 以确认已接收。

## 请求头

| 请求头 | 说明 |
| - | - |
| `signature` | 原始请求体的 RSA-SHA256 签名，以十六进制编码。请使用您 Webhook 的 `publicKey` 进行验证。请参阅 [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)。 |
| `Content-Type` | `application/json` |

## 订单状态码

| 状态码 | 含义 |
| - | - |
| `10` | 审核中 —— 订单正在审核 |
| `11` | 风控审核 —— 订单正在进行风控审核 |
| `12` | 已上传 RFI 文件 —— 风控审核期间已上传所需文件 |
| `31` | 待提交证明文件 |
| `32` | 等待加密货币充值 |
| `40` | 待支付 —— 等待付款 |
| `50` | 已支付 —— 已收到付款 |
| `60` | 已完成 —— 订单完成 |
| `70` | 已取消 —— 已取消、被拒绝或已超时 |
| `72` | 已退款 —— 订单已退款 |

已取消、在 API 或风控审核中被拒绝、或已超时的订单将以 `orderStatus` `70` 发送。其他状态（例如 `20`、`30`、`71` 和 `73`）不会发送。

## 负载字段

**webhookId** `string`

投递此事件的 Webhook 端点 ID。

**eventType** `string`

对于此事件类型，始终为 `ORDER_WEBHOOK`。

**orderId** `string`

订单的唯一标识符。

**clientId** `string`

您提供的客户端订单标识符。如果您未提供，则省略此字段。

**userId** `string`

您的 VelaFi 账户（用户）ID。

**merchantId** `string`

该订单所属商户的 ID。

**settingsId** `string`

该订单使用的商户账户设置（支付通道）ID。

**orderType** `string`

交易方向：`BUY`（法币 → 加密货币）或 `SELL`（加密货币 → 法币）。

**fiat** `string`

订单涉及的法币，例如 `MXN`。

**fiatAmount** `string`

订单的法币金额。

**arriveFiatAmount** `string`

实际支付或收到的法币金额。

**fiatFee** `string`

订单收取的法币费用。

**crypto** `string`

订单涉及的加密货币，例如 `USDT`。

**cryptoAmount** `string`

订单的加密货币金额。

**orderPrice** `string`

订单成交时的汇率（每单位加密货币对应的法币数量）。

**orderStatus** `string`

当前订单状态码。请参阅上方状态表。

**failCode** `string`

机器可读的失败代码。仅在已取消（`70`）或已退款（`72`）且记录了失败代码的订单中出现；否则省略。

**failReason** `string`

可读的失败描述。仅在存在 `failCode` 且记录了描述时出现。

**createTime** `string`

订单创建时间的 Unix 时间戳（毫秒）。

**updateTime** `string`

订单最后更新时间的 Unix 时间戳（毫秒）。

**timestamp** `string`

本次投递尝试签名时的 Unix 时间戳（毫秒）。

为保持向后兼容，负载中还包含 `fiatCurrency`、`orderAmount`、`arriveOrderAmount`、`mcSettingsId`、`cryptoCurrency` 和 `quantity`，它们分别重复 `fiat`、`fiatAmount`、`arriveFiatAmount`、`settingsId`、`crypto` 和 `cryptoAmount` 的值。部分订单还包含其他字段，例如 `bankOrderId`。请忽略您不使用的任何字段。

## 负载示例

```json Incoming POST body theme={null}
{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "ORDER_WEBHOOK",
  "orderId": "473130522693193728",
  "clientId": "W658784738723",
  "userId": "455472",
  "merchantId": "4",
  "settingsId": "12",
  "orderType": "SELL",
  "fiat": "MXN",
  "fiatAmount": "99",
  "arriveFiatAmount": "99",
  "fiatFee": "0",
  "crypto": "USDT",
  "cryptoAmount": "5",
  "orderPrice": "19.8158",
  "orderStatus": "60",
  "createTime": "1735279907000",
  "updateTime": "1735280582000",
  "fiatCurrency": "MXN",
  "orderAmount": "99",
  "arriveOrderAmount": "99",
  "mcSettingsId": "12",
  "cryptoCurrency": "USDT",
  "quantity": "5",
  "timestamp": "1735280582345"
}
```

## 必需的响应

请以 HTTP 状态码 `200` 返回以下 JSON 响应体以确认接收：

```json Your response theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

> [!NOTE]
>
> 如果您的端点返回非 2xx 状态码、未及时响应或返回其他任何响应体，VelaFi 将重试投递。同一事件可能会多次到达，因此请结合 `orderId` 与 `orderStatus` 进行去重。请参阅[投递与重试](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md#delivery-and-retries)。


## Related topics

- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md)
- [入金提现事件](https://docs.velafi.com/cn/api-reference/webhooks/on-ramp-withdraw-message-push.md)
- [全球支付事件](https://docs.velafi.com/cn/api-reference/webhooks/fiat-fiat-order-message-push.md)
- [稳定币支付事件](https://docs.velafi.com/cn/api-reference/webhooks/stablecoin-payment-order-message-push.md)
- [加密货币提现事件](https://docs.velafi.com/cn/api-reference/webhooks/crypto-withdraw-message-push.md)


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