> ## 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 发送的 GLOBAL_PAYMENT_WEBHOOK 事件负载参考。

当通过 API 创建的法币兑法币全球支付订单进入以下任一状态时，VelaFi 会向您的 `GLOBAL_PAYMENT_WEBHOOK` 端点发送一个已签名的 HTTP POST 请求。负载描述了跨境支付的两端——入金端（来源国家/币种）和出金端（目标国家/币种）——以及当前订单状态。请验证 `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` | 审核中——订单正在进行合规审核 |
| `31` | 待提交文件——必须提供所需文件 |
| `41` | 待收款——等待付款方存入法币 |
| `51` | 待付款——已收到加密货币，法币付款处理中 |
| `60` | 已放款——订单完成 |
| `71` | 收款已取消——入金环节已取消 |
| `72` | 付款已取消——出金环节已取消 |

其他全球支付状态不会推送。

## 负载字段

**webhookId** `string`

推送此事件的 Webhook 端点 ID。

**eventType** `string`

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

**orderId** `string`

全球支付订单的唯一标识符。

**clientId** `string`

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

**userId** `string`

您的 VelaFi 账户（用户）ID。

**onRampCountry** `string`

来源国家名称（例如 `Mexico`）。

**onRampMerchantId** `string`

处理来源端支付的入金商户 ID。未设置时省略。

**onRampFiat** `string`

向付款方收取的法币（例如 `MXN`）。

**onRampFiatAmount** `string`

以来源币种向付款方收取的金额。

**onRampFiatFee** `string`

入金端收取的费用。未设置时省略。

**offRampCountry** `string`

目标国家名称（例如 `Hong Kong`）。

**offRampMerchantId** `string`

处理目标端支付的出金商户 ID。未设置时省略。

**offRampFiat** `string`

交付给收款人的法币（例如 `USD`）。

**offRampFiatAmount** `string`

以目标币种交付给收款人的金额。

**offRampFiatFee** `string`

出金端收取的费用。未设置时省略。

**orderPrice** `string`

入金币种与出金币种之间的实际汇率。

**orderStatus** `string`

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

**createTime** `string`

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

**updateTime** `string`

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

**timestamp** `string`

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

## 负载示例

```json Incoming POST body theme={null}
{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "GLOBAL_PAYMENT_WEBHOOK",
  "orderId": "473130522693193728",
  "clientId": "W658784738723",
  "userId": "455472",
  "onRampCountry": "Mexico",
  "onRampMerchantId": "3",
  "onRampFiat": "MXN",
  "onRampFiatAmount": "100",
  "onRampFiatFee": "0",
  "offRampCountry": "Hong Kong",
  "offRampMerchantId": "4",
  "offRampFiat": "USD",
  "offRampFiatAmount": "18",
  "offRampFiatFee": "2",
  "orderPrice": "20",
  "orderStatus": "41",
  "createTime": "1735279907000",
  "updateTime": "1735280582000",
  "timestamp": "1735280582345"
}
```

## 必需的响应

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

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

> [!NOTE]
>
> 此 Webhook 仅针对上面列出的状态触发。如果在尝试推送时订单已进入后续状态，某个状态可能会被跳过。同一事件可能会多次送达，因此请结合 `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/docs/guides/global-payments.md)
- [稳定币支付事件](https://docs.velafi.com/cn/api-reference/webhooks/stablecoin-payment-order-message-push.md)
- [创建全球支付订单](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-fiat-order.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)


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