订单
创建全球支付订单
创建法币兑法币的全球支付订单。资金以一个国家的法币收取，并通过稳定币通道以另一个国家的法币支付。
POST
/
v2
/
order
/
fiat_to_fiat
创建全球支付订单
curl --request POST \
--url https://api-test.velafi.com/v2/order/fiat_to_fiat \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"onRampCountry": "<string>",
"onRampFiat": "<string>",
"onRampPaymentId": 123,
"onRampMerchantId": 123,
"onRampFiatAmount": 123,
"depositAlias": "<string>",
"offRampCountry": "<string>",
"offRampFiat": "<string>",
"offRampPaymentId": 123,
"offRampMerchantId": 123,
"offRampFiatAmount": 123,
"clientId": "<string>",
"remark": "<string>",
"quoteId": "<string>",
"inFieldJson": {
"inFieldJson.bank": "<string>"
}
}
'import requests
url = "https://api-test.velafi.com/v2/order/fiat_to_fiat"
payload = {
"onRampCountry": "<string>",
"onRampFiat": "<string>",
"onRampPaymentId": 123,
"onRampMerchantId": 123,
"onRampFiatAmount": 123,
"depositAlias": "<string>",
"offRampCountry": "<string>",
"offRampFiat": "<string>",
"offRampPaymentId": 123,
"offRampMerchantId": 123,
"offRampFiatAmount": 123,
"clientId": "<string>",
"remark": "<string>",
"quoteId": "<string>",
"inFieldJson": { "inFieldJson.bank": "<string>" }
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
onRampCountry: '<string>',
onRampFiat: '<string>',
onRampPaymentId: 123,
onRampMerchantId: 123,
onRampFiatAmount: 123,
depositAlias: '<string>',
offRampCountry: '<string>',
offRampFiat: '<string>',
offRampPaymentId: 123,
offRampMerchantId: 123,
offRampFiatAmount: 123,
clientId: '<string>',
remark: '<string>',
quoteId: '<string>',
inFieldJson: {'inFieldJson.bank': '<string>'}
})
};
fetch('https://api-test.velafi.com/v2/order/fiat_to_fiat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/order/fiat_to_fiat")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"onRampCountry\": \"<string>\",\n \"onRampFiat\": \"<string>\",\n \"onRampPaymentId\": 123,\n \"onRampMerchantId\": 123,\n \"onRampFiatAmount\": 123,\n \"depositAlias\": \"<string>\",\n \"offRampCountry\": \"<string>\",\n \"offRampFiat\": \"<string>\",\n \"offRampPaymentId\": 123,\n \"offRampMerchantId\": 123,\n \"offRampFiatAmount\": 123,\n \"clientId\": \"<string>\",\n \"remark\": \"<string>\",\n \"quoteId\": \"<string>\",\n \"inFieldJson\": {\n \"inFieldJson.bank\": \"<string>\"\n }\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": 123
}
}法币兑法币全球支付路线让您无需在应用层接触加密货币即可跨境转移资金——VelaFi 会在内部通过稳定币通道处理入金和出金两个环节。您可以在一次 API 调用中同时配置入金环节（收取资金的一方）和出金环节（交付资金的一方）。可以在入金端（
onRampFiatAmount）或出金端（offRampFiatAmount）固定金额；如果两者都传入，则以 onRampFiatAmount 为准。来自法币/法币报价 API 的 quoteId 可锁定跨币种汇率。
端点
POST https://api.velafi.com/v2/order/fiat_to_fiat
沙盒环境测试请使用
https://api-test.velafi.com/v2/order/fiat_to_fiat。请求头
| 请求头 | 值 |
|---|---|
X-BH-TOKEN | 通过 GET /v2/token/generate 获取的令牌 |
Content-Type | application/json |
请求体参数
入金环节
string
必填
收取法币所在国家的完整名称（例如
"Mexico"）。string
必填
付款方支付所用的 ISO 4217 法币代码（例如
"MXN"）。integer
必填
用于收取入金法币的数字支付方式 ID。支持的取值请参阅支付方式 ID。
integer
必填
入金环节的商户 ID。没有有效入金商户的请求将被拒绝。
decimal
付款方支付的法币金额（例如
1000.00）。请提供 onRampFiatAmount 或 offRampFiatAmount；如果两者都传入，则以 onRampFiatAmount 为准。string
用于入金法币存款的虚拟账户别名。
出金环节
string
必填
交付法币所在国家的完整名称（例如
"Argentina"）。string
必填
收款人接收的 ISO 4217 法币代码（例如
"ARS"）。integer
必填
接收出金法币的收款人的数字用户支付 ID。必须是
GET /v2/payments 返回的有效 userPaymentId。integer
必填
出金环节的商户 ID。没有有效出金商户的请求将被拒绝。
decimal
收款人收到的法币金额（例如
55000.00）。当同时传入值不低于 0.01 的 onRampFiatAmount 时，此参数将被忽略。共享参数
string
您自己的订单参考 ID。最多 40 个字符。它在您账户下所有
fiat_to_fiat 订单中必须唯一；使用相同 clientId 的第二次创建请求将被拒绝。该值会在获取订单和列出订单的响应中返回。请参阅幂等性与重试。string
附加到订单的可选自由文本备注。
string
来自报价 API 的报价 ID，用于锁定跨币种汇率。
object
响应字段
integer
响应状态码。
200 表示成功。string
人类可读的响应消息。
示例
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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"orderId": 1123123123
}
}
使用
GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat 获取法币兑法币订单的详细状态。响应包含独立的入金和出金支付信息对象，以及一套独立的状态码（例如 41 待收款、51 待付款、60 已完成；请参阅订单状态）。幂等性与重试
使用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 重试：如果第一次请求在此期间确实创建了订单，重试将作为重复请求被拒绝，而不会创建第二个订单。
quoteId 可能会被一个随后被拒绝的创建请求消耗。重试前请重新申请报价。⌘I
创建全球支付订单
curl --request POST \
--url https://api-test.velafi.com/v2/order/fiat_to_fiat \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"onRampCountry": "<string>",
"onRampFiat": "<string>",
"onRampPaymentId": 123,
"onRampMerchantId": 123,
"onRampFiatAmount": 123,
"depositAlias": "<string>",
"offRampCountry": "<string>",
"offRampFiat": "<string>",
"offRampPaymentId": 123,
"offRampMerchantId": 123,
"offRampFiatAmount": 123,
"clientId": "<string>",
"remark": "<string>",
"quoteId": "<string>",
"inFieldJson": {
"inFieldJson.bank": "<string>"
}
}
'import requests
url = "https://api-test.velafi.com/v2/order/fiat_to_fiat"
payload = {
"onRampCountry": "<string>",
"onRampFiat": "<string>",
"onRampPaymentId": 123,
"onRampMerchantId": 123,
"onRampFiatAmount": 123,
"depositAlias": "<string>",
"offRampCountry": "<string>",
"offRampFiat": "<string>",
"offRampPaymentId": 123,
"offRampMerchantId": 123,
"offRampFiatAmount": 123,
"clientId": "<string>",
"remark": "<string>",
"quoteId": "<string>",
"inFieldJson": { "inFieldJson.bank": "<string>" }
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
onRampCountry: '<string>',
onRampFiat: '<string>',
onRampPaymentId: 123,
onRampMerchantId: 123,
onRampFiatAmount: 123,
depositAlias: '<string>',
offRampCountry: '<string>',
offRampFiat: '<string>',
offRampPaymentId: 123,
offRampMerchantId: 123,
offRampFiatAmount: 123,
clientId: '<string>',
remark: '<string>',
quoteId: '<string>',
inFieldJson: {'inFieldJson.bank': '<string>'}
})
};
fetch('https://api-test.velafi.com/v2/order/fiat_to_fiat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/order/fiat_to_fiat")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"onRampCountry\": \"<string>\",\n \"onRampFiat\": \"<string>\",\n \"onRampPaymentId\": 123,\n \"onRampMerchantId\": 123,\n \"onRampFiatAmount\": 123,\n \"depositAlias\": \"<string>\",\n \"offRampCountry\": \"<string>\",\n \"offRampFiat\": \"<string>\",\n \"offRampPaymentId\": 123,\n \"offRampMerchantId\": 123,\n \"offRampFiatAmount\": 123,\n \"clientId\": \"<string>\",\n \"remark\": \"<string>\",\n \"quoteId\": \"<string>\",\n \"inFieldJson\": {\n \"inFieldJson.bank\": \"<string>\"\n }\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": 123
}
}