Orders
Get an Order
Retrieve full details and current status for a single order by its ID. Supports fiat-to-crypto, crypto-to-fiat, and fiat-to-fiat order types.
GET
/
v2
/
order
/
detail
Get an Order
curl --request GET \
--url https://api-test.velafi.com/v2/order/detail \
--header 'X-BH-TOKEN: <api-key>'import requests
url = "https://api-test.velafi.com/v2/order/detail"
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};
fetch('https://api-test.velafi.com/v2/order/detail', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://api-test.velafi.com/v2/order/detail")
.header("X-BH-TOKEN", "<api-key>")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": "<string>",
"data.clientId": "<string>",
"data.onRampMerchantId": 123,
"data.onRampPaymentId": 123,
"data.onRampCountry": "<string>",
"data.onRampFiat": "<string>",
"data.onRampFiatAmount": "<string>",
"data.onRampFiatFee": "<string>",
"data.offRampMerchantId": 123,
"data.offRampPaymentId": 123,
"data.offRampCountry": "<string>",
"data.offRampFiat": "<string>",
"data.offRampFiatAmount": "<string>",
"data.offArriveRampFiatAmount": "<string>",
"data.offRampFiatFee": "<string>",
"data.orderPrice": "<string>",
"data.orderStatus": 123,
"data.onRampPaymentInfo": {},
"data.offRampPaymentInfo": {},
"data.createTime": "<string>",
"data.completedTime": "<string>",
"data.onRampOrderFeeDetail": {},
"data.offRampOrderFeeDetail": {}
}
}Use this endpoint to fetch the complete state of any order — payment instructions, exchange rate, amounts, timestamps, and the current status code. Because the response schema differs between single-currency orders (
fiat_to_crypto / crypto_to_fiat) and cross-currency orders (fiat_to_fiat), you must supply the orderType query parameter, together with orderId (or, for fiat_to_crypto and crypto_to_fiat orders, your clientId). Poll this endpoint to drive status-based logic in your application, such as displaying payment instructions to the user or triggering downstream processes once orderStatus reaches 60 (completed).
Endpoint
GET https://api.velafi.com/v2/order/detail
Use
https://api-test.velafi.com/v2/order/detail for sandbox testing.Query Parameters
integer
The unique numeric ID of the order to retrieve. Required for
fiat_to_fiat orders. For fiat_to_crypto and crypto_to_fiat orders, send either orderId or clientId; if both are sent, orderId is used.string
The
clientId you supplied when creating the order. Supported for fiat_to_crypto and crypto_to_fiat orders only.string
required
The type of the order. Must be one of
fiat_to_crypto, crypto_to_fiat, or fiat_to_fiat.Order Status Codes
orderStatus uses one set of codes for fiat_to_crypto / crypto_to_fiat orders and another for fiat_to_fiat orders.
| Order type | Codes you can receive |
|---|---|
fiat_to_crypto, crypto_to_fiat | 10, 11, 12, 31, 32, 40, 50, 60, 70, 71, 72, 73, 80, 81 |
fiat_to_fiat | 10, 11, 12, 31, 41, 51, 60, 71, 72, 90 |
Ramp orders that VelaFi creates for your account (not through the API or the dashboard) can also show
20 (review rejected) or 30 (approved).Response Fields — Fiat-to-Crypto / Crypto-to-Fiat
integer
Response status code.
200 indicates success.string
Human-readable response message.
object
Order detail object.
Show data fields
Show data fields
string
Unique order ID.
string
Your custom order reference ID, as supplied at creation.
integer
Merchant ID associated with this order.
integer
Payment method ID (populated for
fiat_to_crypto orders).integer
User payment (beneficiary) ID (populated for
crypto_to_fiat orders).string
Country name for this order.
string
Cryptocurrency ticker (e.g.,
"USDT").string
Fiat currency code (e.g.,
"MXN").string
Order type:
fiat_to_crypto or crypto_to_fiat.string
Exchange rate at order creation (fiat per crypto unit).
string
Crypto amount involved in the order.
string
Fiat amount involved in the order.
string
Fee charged in fiat currency.
integer
Current order status code. See the status table above.
string
National central bank transaction reference number.
object
Key-value map of payment instructions for this order (e.g., CLABE number for Mexican SPEI orders). Contents vary by country and payment method.
integer
Error code recorded for a failed order.
0 when no failure code is recorded.string
Human-readable description of why the order failed.
string
Unix timestamp (milliseconds) when the order was created.
string
Unix timestamp (milliseconds) when the order reached a final status. Until then, it equals
createTime.string
Returned only while the order is in
status: 32 (awaiting crypto deposit, post-funded off-ramp). The deadline, as a Unix timestamp in seconds, for the merchant’s crypto balance to cover the order.string
Bank-side reference for the order. Currently populated mainly for ARS orders.
object
Itemized fee breakdown. Fee lines are listed only for orders that have itemized fees recorded.
Show orderFeeDetail fields
Show orderFeeDetail fields
string
Gross fiat amount of the order, including the fees listed in
feeLines.string
grossAmount minus the sum of the fee lines’ amount.array
One entry per fee. Each entry has
feeType (for example, CONVERT_FEE), rate (a decimal fraction; multiply by 100 for a percentage), fixed (fixed fee), receivableAmount (fee due before any waiver), amount (fee actually charged), currency, and hasWaived (1 if the fee was waived, 0 otherwise).Response Fields — Fiat-to-Fiat
object
Fiat-to-fiat order detail object.
Show data fields
Show data fields
string
Unique order ID.
string
Your custom order reference ID.
integer
Merchant ID for the on-ramp leg.
integer
Payment method ID for the on-ramp leg.
string
Country where fiat is collected.
string
Fiat currency collected on the on-ramp leg.
string
Amount collected on the on-ramp leg.
string
Fee for the on-ramp leg.
integer
Merchant ID for the off-ramp leg.
integer
Beneficiary payment ID for the off-ramp leg.
string
Country where fiat is delivered.
string
Fiat currency delivered on the off-ramp leg.
string
Amount to be delivered before fees.
string
Net amount that arrives to the beneficiary after fees.
string
Fee for the off-ramp leg.
string
Cross-currency exchange rate at order creation.
integer
Current order status. See fiat-to-fiat status codes above.
object
Payment instructions for the on-ramp leg (e.g., CLABE for MXN).
object
Payment instructions for the off-ramp leg.
string
Unix timestamp (milliseconds) when the order was created.
string
Unix timestamp (milliseconds) when the order completed.
object
Itemized fee breakdown for the on-ramp leg. Same structure as
orderFeeDetail above.object
Itemized fee breakdown for the off-ramp leg. Same structure as
orderFeeDetail above.Examples
- Fiat-to-Crypto Order
- Fiat-to-Fiat Order
curl -X GET "https://api.velafi.com/v2/order/detail?orderId=493829236956962816&orderType=fiat_to_crypto" \
-H "X-BH-TOKEN: YOUR_TOKEN"
{
"code": 200,
"msg": "SUCCESS",
"data": {
"orderId": "493829236956962816",
"clientId": "f_c_0250222004",
"merchantId": 3,
"paymentId": 0,
"userPaymentId": 0,
"country": "Mexico",
"crypto": "USDT",
"fiat": "MXN",
"orderType": "fiat_to_crypto",
"orderPrice": "21.4104",
"cryptoAmount": "5.1376",
"fiatAmount": "110",
"fiatFee": "0",
"orderStatus": 60,
"hasRefund": 0,
"failCode": 0,
"failReason": "",
"traceNumber": "20241223907069062e51744c4f0e57",
"paymentInfo": {
"Cuenta CLABE": "000000000000000001"
},
"createTime": "1740214865000",
"completedTime": "1740214866000"
}
}
curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
-H "X-BH-TOKEN: YOUR_TOKEN"
{
"code": 200,
"msg": "SUCCESS",
"data": {
"orderId": "494541042692263936",
"clientId": "c_f_0250224003",
"onRampMerchantId": 3,
"onRampPaymentId": 17,
"onRampCountry": "Mexico",
"onRampFiat": "MXN",
"onRampFiatAmount": "110",
"onRampFiatFee": "1",
"offRampCountry": "Argentina",
"offRampMerchantId": 4,
"offRampPaymentId": 134,
"offRampFiat": "ARS",
"offRampFiatAmount": "6156.3",
"offArriveRampFiatAmount": "6155.3",
"offRampFiatFee": "1",
"orderPrice": "55.9664",
"orderStatus": 31,
"onRampPaymentInfo": {
"Cuenta CLABE": "000000000000000001"
},
"offRampPaymentInfo": {
"CVU/CBU": "0000000000000000000002"
},
"createTime": "1740384573000",
"completedTime": "1740384573000"
}
}
Was this page helpful?
⌘I
Get an Order
curl --request GET \
--url https://api-test.velafi.com/v2/order/detail \
--header 'X-BH-TOKEN: <api-key>'import requests
url = "https://api-test.velafi.com/v2/order/detail"
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};
fetch('https://api-test.velafi.com/v2/order/detail', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://api-test.velafi.com/v2/order/detail")
.header("X-BH-TOKEN", "<api-key>")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": "<string>",
"data.clientId": "<string>",
"data.onRampMerchantId": 123,
"data.onRampPaymentId": 123,
"data.onRampCountry": "<string>",
"data.onRampFiat": "<string>",
"data.onRampFiatAmount": "<string>",
"data.onRampFiatFee": "<string>",
"data.offRampMerchantId": 123,
"data.offRampPaymentId": 123,
"data.offRampCountry": "<string>",
"data.offRampFiat": "<string>",
"data.offRampFiatAmount": "<string>",
"data.offArriveRampFiatAmount": "<string>",
"data.offRampFiatFee": "<string>",
"data.orderPrice": "<string>",
"data.orderStatus": 123,
"data.onRampPaymentInfo": {},
"data.offRampPaymentInfo": {},
"data.createTime": "<string>",
"data.completedTime": "<string>",
"data.onRampOrderFeeDetail": {},
"data.offRampOrderFeeDetail": {}
}
}