Órdenes
Obtener una orden
Obtén el detalle completo y el estado actual de una orden por su ID. Admite órdenes de tipo fiat a cripto, cripto a fiat y fiat a fiat.
GET
/
v2
/
order
/
detail
Obtener una orden
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": {}
}
}Usa este endpoint para obtener el estado completo de cualquier orden: instrucciones de pago, tipo de cambio, montos, marcas de tiempo y el código de estado actual. Como el esquema de la respuesta es distinto entre las órdenes de una sola moneda (
fiat_to_crypto / crypto_to_fiat) y las órdenes entre monedas (fiat_to_fiat), debes enviar el parámetro de consulta orderType, junto con orderId (o, para órdenes fiat_to_crypto y crypto_to_fiat, tu clientId). Consulta este endpoint periódicamente para controlar la lógica basada en estados de tu aplicación, por ejemplo para mostrar las instrucciones de pago al usuario o para disparar procesos posteriores cuando orderStatus llegue a 60 (completada).
Endpoint
GET https://api.velafi.com/v2/order/detail
Usa
https://api-test.velafi.com/v2/order/detail para pruebas en sandbox.Parámetros de consulta
integer
ID numérico único de la orden que quieres consultar. Obligatorio para órdenes
fiat_to_fiat. Para órdenes fiat_to_crypto y crypto_to_fiat, envía orderId o clientId; si envías ambos, se usa orderId.string
El
clientId que enviaste al crear la orden. Solo se admite para órdenes fiat_to_crypto y crypto_to_fiat.string
requerido
Tipo de la orden. Debe ser
fiat_to_crypto, crypto_to_fiat o fiat_to_fiat.Códigos de estado de la orden
orderStatus usa un conjunto de códigos para las órdenes fiat_to_crypto / crypto_to_fiat y otro para las órdenes fiat_to_fiat.
| Tipo de orden | Códigos que puedes recibir |
|---|---|
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 |
Las órdenes de on-ramp/off-ramp que VelaFi crea para tu cuenta (no a través de la API ni del panel) también pueden mostrar
20 (revisión rechazada) o 30 (aprobada).Campos de la respuesta: fiat a cripto / cripto a fiat
integer
Código de estado de la respuesta.
200 indica éxito.string
Mensaje de respuesta legible.
object
Objeto con el detalle de la orden.
Mostrar campos de data
Mostrar campos de data
string
ID único de la orden.
string
Tu ID de referencia personalizado de la orden, tal como lo enviaste al crearla.
integer
ID del comercio asociado a esta orden.
integer
ID del método de pago (se llena en órdenes
fiat_to_crypto).integer
ID del pago del usuario (beneficiario) (se llena en órdenes
crypto_to_fiat).string
Nombre del país de esta orden.
string
Símbolo de la criptomoneda (p. ej.,
"USDT").string
Código de la moneda fiat (p. ej.,
"MXN").string
Tipo de orden:
fiat_to_crypto o crypto_to_fiat.string
Tipo de cambio al crear la orden (fiat por unidad de cripto).
string
Monto en cripto de la orden.
string
Monto en fiat de la orden.
string
Comisión cobrada en moneda fiat.
integer
Código de estado actual de la orden. Consulta la tabla de estados anterior.
string
Número de referencia de la transacción del banco central nacional.
object
Mapa clave-valor con las instrucciones de pago de esta orden (p. ej., el número CLABE para órdenes SPEI en México). El contenido varía según el país y el método de pago.
integer
Código de error registrado para una orden fallida.
0 cuando no hay código de falla registrado.string
Descripción legible del motivo por el que falló la orden.
string
Marca de tiempo Unix (milisegundos) en que se creó la orden.
string
Marca de tiempo Unix (milisegundos) en que la orden llegó a un estado final. Hasta entonces, es igual a
createTime.string
Solo se devuelve mientras la orden está en
status: 32 (en espera del depósito de cripto, off-ramp con fondeo posterior). Es la fecha límite, como marca de tiempo Unix en segundos, para que el saldo en cripto del comercio cubra la orden.string
Referencia de la orden del lado del banco. Actualmente se llena principalmente en órdenes ARS.
object
Desglose detallado de comisiones. Las líneas de comisión solo se listan en órdenes que tienen comisiones desglosadas registradas.
Mostrar campos de orderFeeDetail
Mostrar campos de orderFeeDetail
string
Monto fiat bruto de la orden, incluidas las comisiones listadas en
feeLines.string
grossAmount menos la suma del amount de las líneas de comisión.array
Una entrada por comisión. Cada entrada tiene
feeType (por ejemplo, CONVERT_FEE), rate (fracción decimal; multiplica por 100 para obtener un porcentaje), fixed (comisión fija), receivableAmount (comisión adeudada antes de cualquier exención), amount (comisión cobrada realmente), currency y hasWaived (1 si la comisión se exentó, 0 en caso contrario).Campos de la respuesta: fiat a fiat
object
Objeto con el detalle de la orden fiat a fiat.
Mostrar campos de data
Mostrar campos de data
string
ID único de la orden.
string
Tu ID de referencia personalizado de la orden.
integer
ID del comercio del tramo de on-ramp.
integer
ID del método de pago del tramo de on-ramp.
string
País donde se recauda el fiat.
string
Moneda fiat recaudada en el tramo de on-ramp.
string
Monto recaudado en el tramo de on-ramp.
string
Comisión del tramo de on-ramp.
integer
ID del comercio del tramo de off-ramp.
integer
ID del pago del beneficiario del tramo de off-ramp.
string
País donde se entrega el fiat.
string
Moneda fiat entregada en el tramo de off-ramp.
string
Monto a entregar antes de comisiones.
string
Monto neto que llega al beneficiario después de comisiones.
string
Comisión del tramo de off-ramp.
string
Tipo de cambio entre monedas al crear la orden.
integer
Estado actual de la orden. Consulta los códigos de estado fiat a fiat anteriores.
object
Instrucciones de pago del tramo de on-ramp (p. ej., CLABE para MXN).
object
Instrucciones de pago del tramo de off-ramp.
string
Marca de tiempo Unix (milisegundos) en que se creó la orden.
string
Marca de tiempo Unix (milisegundos) en que se completó la orden.
object
Desglose detallado de comisiones del tramo de on-ramp. Misma estructura que
orderFeeDetail arriba.object
Desglose detallado de comisiones del tramo de off-ramp. Misma estructura que
orderFeeDetail arriba.Ejemplos
- Orden fiat a cripto
- Orden fiat a fiat
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"
}
}
⌘I
Obtener una orden
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": {}
}
}