> ## 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 会在内部通过稳定币通道处理入金和出金两个环节。您可以在一次 API 调用中同时配置入金环节（收取资金的一方）和出金环节（交付资金的一方）。可以在入金端（`onRampFiatAmount`）或出金端（`offRampFiatAmount`）固定金额；如果两者都传入，则以 `onRampFiatAmount` 为准。来自法币/法币报价 API 的 `quoteId` 可锁定跨币种汇率。

## 端点

```text theme={null}
POST https://api.velafi.com/v2/order/fiat_to_fiat
```

> [!NOTE]
>
> 沙盒环境测试请使用 `https://api-test.velafi.com/v2/order/fiat_to_fiat`。

## 请求头

| 请求头 | 值 |
| - | - |
| `X-BH-TOKEN` | 通过 `GET /v2/token/generate` 获取的令牌 |
| `Content-Type` | `application/json` |

## 请求体参数

### 入金环节

**onRampCountry** `string` *required*

收取法币所在国家的完整名称（例如 `"Mexico"`）。

**onRampFiat** `string` *required*

付款方支付所用的 ISO 4217 法币代码（例如 `"MXN"`）。

**onRampPaymentId** `integer` *required*

用于收取入金法币的数字支付方式 ID。支持的取值请参阅支付方式 ID。

**onRampMerchantId** `integer` *required*

入金环节的商户 ID。没有有效入金商户的请求将被拒绝。

**onRampFiatAmount** `decimal`

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

**depositAlias** `string`

用于入金法币存款的虚拟账户别名。

### 出金环节

**offRampCountry** `string` *required*

交付法币所在国家的完整名称（例如 `"Argentina"`）。

**offRampFiat** `string` *required*

收款人接收的 ISO 4217 法币代码（例如 `"ARS"`）。

**offRampPaymentId** `integer` *required*

接收出金法币的收款人的数字用户支付 ID。必须是 `GET /v2/payments` 返回的有效 `userPaymentId`。

**offRampMerchantId** `integer` *required*

出金环节的商户 ID。没有有效出金商户的请求将被拒绝。

**offRampFiatAmount** `decimal`

收款人收到的法币金额（例如 `55000.00`）。当同时传入值不低于 0.01 的 `onRampFiatAmount` 时，此参数将被忽略。

### 共享参数

**clientId** `string`

您自己的订单参考 ID。最多 40 个字符。它在您账户下所有 `fiat_to_fiat` 订单中必须唯一；使用相同 `clientId` 的第二次创建请求将被拒绝。该值会在获取订单和列出订单的响应中返回。请参阅[幂等性与重试](#idempotency-and-retries)。

**remark** `string`

附加到订单的可选自由文本备注。

**quoteId** `string`

来自报价 API 的报价 ID，用于锁定跨币种汇率。

**inFieldJson** `object`

某些支付方式所需的额外支付专用字段。

**inFieldJson 字段**

**inFieldJson.bank** `string`

当 `onRampPaymentId` 为 `141`（哥伦比亚银行转账）时必填的银行代码。请参阅[哥伦比亚银行代码](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md#哥伦比亚银行代码)。

## 响应字段

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

人类可读的响应消息。

**data** `object`

订单结果对象。

**data 字段**

**data.orderId** `integer`

所创建订单的唯一数字 ID。使用它可获取完整的订单状态和付款说明。

## 示例

```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": "my-global-pay-2024-001",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 3,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 105,
    "depositAlias": "tom_alias",
    "offRampCountry": "Argentina",
    "offRampMerchantId": 4,
    "offRampFiat": "ARS",
    "offRampPaymentId": 134,
    "remark": "Supplier payment",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
  }'
```

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

> [!TIP]
>
> 使用 `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat` 获取法币兑法币订单的详细状态。响应包含独立的入金和出金支付信息对象，以及一套独立的状态码（例如 `41` 待收款、`51` 待付款、`60` 已完成；请参阅[订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)）。

## 幂等性与重试

使用 `clientId` 可以让订单创建安全地重试。

* `clientId` 为可选参数。最多 40 个字符。它在您账户下所有商户的全部 `fiat_to_fiat` 订单中必须唯一。
* 复用已有 `clientId` 的创建请求会因重复提交错误而被拒绝，且不会创建新订单。
* `clientId` 会永久绑定到其订单，即使订单被取消也是如此。新订单请使用新的 `clientId`。
* `GET /v2/order/detail` 仅按 `orderId` 查询 `fiat_to_fiat` 订单。如需按 `clientId` 查找订单，请使用 `GET /v2/orders?orderType=fiat_to_fiat` 列出最近的订单，并匹配 `clientId` 字段。

如果创建请求超时或没有返回响应，请先在订单列表中查找其 `clientId`。如果订单已存在，请勿再次创建。如果不存在，请使用相同的 `clientId` 重试：如果第一次请求在此期间确实创建了订单，重试将作为重复请求被拒绝，而不会创建第二个订单。

> [!NOTE]
>
> `quoteId` 可能会被一个随后被拒绝的创建请求消耗。重试前请重新申请报价。


## Related topics

- [全球支付（法币兑法币）](https://docs.velafi.com/cn/docs/guides/global-payments.md)
- [订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)
- [全球支付事件](https://docs.velafi.com/cn/api-reference/webhooks/fiat-fiat-order-message-push.md)
- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md)
- [创建 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/create-webhook-endpoints.md)


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