> ## 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 基于稳定币的全球支付通道，跨境发送法币，并将本地法币交付至任意银行账户。

VelaFi 的法币兑法币全球支付让您可以在不同国家之间转移资金，而无需付款方或收款方持有任何加密货币。在底层，VelaFi 通过稳定币通道桥接两种本地货币 —— 先将付款方的法币兑换为稳定币，进行跨境路由，再兑换回收款方的本地法币并直接存入其银行账户。整个流程被抽象为一次 API 调用，让您无需构建或维护任何外汇或加密货币基础设施即可具备跨境支付能力。

## 工作原理

### 确认前提条件

每笔全球支付都涉及两个商户账户 —— 转账两端各一个：

* **付款商户（入金端）** —— 必须已为付款国家和币种开通入金法币账户。
* **收款商户（出金端）** —— 必须已为收款国家和币种开通出金法币账户。
* **已注册收款人** —— 收款方的银行账户必须已作为收款人添加到出金商户下。创建订单时需要由此生成的 `offRampPaymentId`（即 `userPaymentId`）。
* **已获取 API 密钥** —— 所有请求都需要 `X-BH-TOKEN` 请求头。

### 获取报价（可选）

在创建订单之前请求实时跨币种汇率。该汇率反映完整的入金 → 稳定币 → 出金兑换链路。

**端点：** `GET /v2/user/fiat-quote`

将付款国家、付款法币、收款国家和收款法币作为查询参数传入。响应返回当前的 `price`（每单位付款法币对应的收款法币数量），并且在设置 `createQuoteId=true` 时返回一个一次性的 `quoteId`，该 ID 在生产环境中锁定汇率 20 秒（在沙盒环境中为 300 秒）。

> [!TIP]
>
> 在创建订单的请求中传入返回的 `quoteId`，以确保按报价汇率成交。如果省略，订单将按下单时的实时市场汇率执行。

### 创建全球支付订单

向 `/v2/order/fiat_to_fiat` 提交 `POST` 请求。VelaFi 会接收入金法币，通过稳定币通道进行兑换，并向收款人发起出金付款。

**端点：** `POST /v2/order/fiat_to_fiat`

#### 请求参数

**onRampCountry** `string` *required*

付款国家名称（例如 `"Mexico"`）。

**onRampFiat** `string` *required*

付款方支付的法币（例如 `"MXN"`）。

**onRampPaymentId** `number` *required*

入金存款的支付方式 ID（例如墨西哥的 SPEI）。请参阅[支付方式 ID](https://docs.velafi.com/cn/docs/payment-methods.md)。

**offRampCountry** `string` *required*

收款国家名称（例如 `"Argentina"`）。

**offRampFiat** `string` *required*

收款方收到的法币（例如 `"ARS"`）。

**offRampPaymentId** `number` *required*

出金付款的收款人支付 ID —— 即已注册收款人记录中的 `userPaymentId`。请参阅[获取收款人](https://docs.velafi.com/cn/api-reference/beneficiary/get-beneficiary.md)。

**onRampFiatAmount** `decimal`

付款方支付的法币金额（例如 `1000.00`）。请提供 `onRampFiatAmount` 或 `offRampFiatAmount` 之一；如果两者都传入，则使用 `onRampFiatAmount`。

**offRampFiatAmount** `decimal`

收款方应收到的目标金额（例如 `55966.40`）。仅在未传入 `onRampFiatAmount` 时使用。

**quoteId** `string`

来自 `GET /v2/user/fiat-quote` 的报价 ID。传入此值以锁定报价汇率。

**clientId** `string`

您自己的订单参考 ID。最多 40 个字符；在您所有 `fiat_to_fiat` 订单中必须唯一，重复的 `clientId` 将被拒绝。该值会在后续订单查询中返回。请参阅[幂等性与重试](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-fiat-order.md#idempotency-and-retries)。

**onRampMerchantId** `number` *required*

入金（付款）商户的 ID。没有有效入金商户的请求将被拒绝。

**offRampMerchantId** `number` *required*

出金（收款）商户的 ID。没有有效出金商户的请求将被拒绝。

**depositAlias** `string`

与入金存款关联的虚拟账户别名（如果您的配置使用虚拟账户路由）。

**inFieldJson** `object`

某些支付方式所需的附加结构化字段。

**inFieldJson 字段**

**inFieldJson.bank** `enum`

使用哥伦比亚入金支付方式（例如 `onRampPaymentId=141`）时所需的银行代码。请参阅[哥伦比亚银行代码列表](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md#哥伦比亚银行代码)。

**remark** `string`

附加在订单上供您参考的自由文本备注。

#### 请求示例

```bash theme={null}
curl -X POST https://api.velafi.com/v2/order/fiat_to_fiat \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "gp-order-001",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 3,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 105,
          "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampFiat": "ARS",
    "offRampPaymentId": 134,
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "remark": "Cross-border payment for invoice #9901"
  }'
```

#### 响应示例

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": 1123123123
  }
}
```

### 监控订单状态

使用 `orderType=fiat_to_fiat` 轮询 `GET /v2/order/detail`，或配置一个事件类型为 `GLOBAL_PAYMENT_WEBHOOK` 的 [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md) 以接收实时状态更新。

**端点：** `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat`

#### 请求示例

```bash theme={null}
curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
  -H "X-BH-TOKEN: YOUR_TOKEN"
```

#### 响应示例

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "494541042692263936",
    "clientId": "gp-order-001",
    "onRampMerchantId": 3,
    "onRampPaymentId": 105,
          "onRampCountry": "Mexico",
    "onRampFiat": "MXN",
    "onRampFiatAmount": "1000",
    "onRampFiatFee": "1",
    "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampPaymentId": 134,
    "offRampFiat": "ARS",
    "offRampFiatAmount": "55966.40",
    "offArriveRampFiatAmount": "55965.40",
    "offRampFiatFee": "1",
    "orderPrice": "55.9664",
    "orderStatus": 60,
    "onRampPaymentInfo": {
      "Cuenta CLABE": "000000000000000001"
    },
    "offRampPaymentInfo": {
      "Cuenta CLABE": "000000000000000003"
    },
    "createTime": "1740384573000",
    "completedTime": "1740384573000"
  }
}
```

#### 响应字段

**orderId** `string`

该订单的唯一标识符。

**clientId** `string`

您自己的参考 ID，从创建请求中原样返回。

**onRampMerchantId** `number`

入金（付款）商户的 ID。

**onRampPaymentId** `number`

入金存款所使用的支付方式 ID。

**onRampCountry** `string`

法币付款的来源国家。

**onRampFiat** `string`

付款方支付的法币。

**onRampFiatAmount** `string`

付款方支付的法币金额。

**onRampFiatFee** `string`

入金端收取的费用。

**offRampCountry** `string`

法币付款的交付国家。

**offRampMerchantId** `number`

出金（收款）商户的 ID。

**offRampPaymentId** `number`

出金付款所使用的收款人支付 ID。

**offRampFiat** `string`

收款人收到的法币。

**offRampFiatAmount** `string`

扣除费用前发送给收款方的法币总额。

**offArriveRampFiatAmount** `string`

扣除费用后实际到达收款方账户的法币净额。

**offRampFiatFee** `string`

出金端收取的费用。

**orderPrice** `string`

订单创建时的汇率（每单位入金法币对应的出金法币数量）。

**orderStatus** `number`

当前状态码。请参阅[订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)。

**onRampPaymentInfo** `object`

入金付款说明（例如付款方存入资金的银行账户）。

**offRampPaymentInfo** `object`

出金付款详情（例如收款方接收资金的银行账户）。

**createTime** `string`

订单创建时间戳，以毫秒为单位（Unix 纪元）。

**completedTime** `string`

订单完成时间戳，以毫秒为单位（Unix 纪元）。

#### 订单状态码

全球支付订单使用其专属的状态码：`10`、`11`、`12`、`31`、`41`、`51`、`60`、`71`、`72` 和 `90`。有关各状态码的含义以及哪些状态码表示订单终结，请参阅[订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)。

## 支持的全球支付交易对

VelaFi 支持以下国家对之间的跨境法币支付。可通过[法币/法币交易对 API 端点](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-fiat-pairs.md)获取完整的最新列表。

| 付款国家 | 付款币种 | 收款国家 | 收款币种 |
| - | - | - | - |
| 🇦🇷 阿根廷 | ARS | 🇲🇽 墨西哥 | MXN |
| 🇦🇷 阿根廷 | ARS | 🇺🇸 美国 | USD |
| 🇧🇷 巴西 | BRL | 🇦🇷 阿根廷 | ARS |
| 🇧🇷 巴西 | BRL | 🇭🇰 中国香港 | USD |
| 🇧🇷 巴西 | BRL | 🌐 全球 | USD |
| 🇨🇴 哥伦比亚 | COP | 🇲🇽 墨西哥 | MXN |
| 🇲🇽 墨西哥 | MXN | 🇦🇷 阿根廷 | ARS |
| 🇲🇽 墨西哥 | MXN | 🇨🇴 哥伦比亚 | COP |
| 🇲🇽 墨西哥 | MXN | 🇭🇰 中国香港 | USD |
| 🇲🇽 墨西哥 | MXN | 🇺🇸 美国 | USD |
| 🇲🇽 墨西哥 | MXN | 🌐 全球 | USD |
| 🇺🇸 美国 | USD | 🇦🇷 阿根廷 | ARS |
| 🇺🇸 美国 | USD | 🇲🇽 墨西哥 | MXN |

> [!NOTE]
>
> “全球”收款区域涵盖不绑定特定国家的 USD 付款 —— 适用于将资金路由至国际 USD 账户。如果您需要此处未列出的交易对，请联系 VelaFi 支持团队。


## Related topics

- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md)
- [出金（加密货币兑法币）](https://docs.velafi.com/cn/docs/guides/off-ramp.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)
- [获取订单](https://docs.velafi.com/cn/api-reference/order/retrieve-a-specific-order.md)
- [获取订单列表](https://docs.velafi.com/cn/api-reference/order/retrieve-a-list-of-orders.md)


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