Orders
Create a Global Payment Order
Create a fiat-to-fiat global payment order. Funds are collected in one country’s fiat and paid out in another’s via stablecoin rails.
POST
/
v2
/
order
/
fiat_to_fiat
Create a Global Payment Order
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
}
}The fiat-to-fiat global payment route lets you move money across borders without touching crypto at the application layer — VelaFi handles the on-ramp and off-ramp legs internally over stablecoin rails. You configure both the on-ramp leg (where funds are collected) and the off-ramp leg (where funds are delivered) in a single API call. Fix the amount on either the on-ramp side (
onRampFiatAmount) or the off-ramp side (offRampFiatAmount); if you send both, onRampFiatAmount takes precedence. A quoteId from the Fiat/Fiat Quote API locks the cross-currency rate.
Endpoint
POST https://api.velafi.com/v2/order/fiat_to_fiat
Use
https://api-test.velafi.com/v2/order/fiat_to_fiat for sandbox testing.Request Headers
| Header | Value |
|---|---|
X-BH-TOKEN | Your token from GET /v2/token/generate |
Content-Type | application/json |
Request Body Parameters
On-Ramp Leg
string
required
Full country name where fiat is collected (e.g.,
"Mexico").string
required
ISO 4217 fiat currency code the sender pays in (e.g.,
"MXN").integer
required
Numeric payment method ID for collecting the on-ramp fiat. See Payment Method IDs for supported values.
integer
required
Merchant ID for the on-ramp leg. Requests without a valid on-ramp merchant are rejected.
decimal
Amount of fiat the sender pays (e.g.,
1000.00). Provide onRampFiatAmount or offRampFiatAmount; if you send both, onRampFiatAmount takes precedence.string
Alias of the virtual account used for the on-ramp fiat deposit.
Off-Ramp Leg
string
required
Full country name where fiat is delivered (e.g.,
"Argentina").string
required
ISO 4217 fiat currency code the beneficiary receives (e.g.,
"ARS").integer
required
Numeric user payment ID of the beneficiary who receives the off-ramp fiat. Must be a valid
userPaymentId returned by GET /v2/payments.integer
required
Merchant ID for the off-ramp leg. Requests without a valid off-ramp merchant are rejected.
decimal
Amount of fiat the beneficiary receives (e.g.,
55000.00). Ignored when onRampFiatAmount is also sent with a value of at least 0.01.Shared Parameters
string
Your own order reference ID. Use at most 40 characters. It must be unique across all
fiat_to_fiat orders on your account; a second create request with the same clientId is rejected. Returned in Get Order and List Orders responses. See Idempotency and retries.string
Optional free-text note attached to the order.
string
Quote ID from the Quote API to lock in the cross-currency exchange rate.
object
Additional payment-specific fields for certain payment methods.
Show inFieldJson fields
Show inFieldJson fields
string
Bank code required when
onRampPaymentId is 141 (Colombian bank transfer). See Colombian Bank Codes.Response Fields
integer
Response status code.
200 indicates success.string
Human-readable response message.
object
Order result object.
Show data fields
Show data fields
integer
The unique numeric ID of the created order. Use this to retrieve the full order status and payment instructions.
Example
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
}
}
Retrieve detailed order status for fiat-to-fiat orders with
GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat. The response includes separate on-ramp and off-ramp payment info objects, and a separate set of status codes (for example 41 pay-in pending, 51 payout pending, 60 completed; see Order Statuses).Idempotency and retries
UseclientId to make order creation safe to retry.
clientIdis optional. Use at most 40 characters. It must be unique across allfiat_to_fiatorders on your account, for all of your merchants.- A create request that reuses an existing
clientIdis rejected with a repeated-submission error, and no new order is created. - A
clientIdstays bound to its order permanently, including after the order is canceled. Use a newclientIdfor a new order. GET /v2/order/detaillooks upfiat_to_fiatorders byorderIdonly. To find an order byclientId, list recent orders withGET /v2/orders?orderType=fiat_to_fiatand match theclientIdfield.
clientId in the order list first. If the order is there, do not create it again. If it is not, retry with the same clientId: if the first request did create the order in the meantime, the retry is rejected as a duplicate instead of creating a second order.
A
quoteId can be consumed by a create request that is then rejected. Request a new quote before you retry.Was this page helpful?
⌘I
Create a Global Payment Order
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
}
}