Órdenes
Crear una orden de pago global
Crea una orden de pago global de fiat a fiat. Los fondos se cobran en la moneda fiat de un país y se pagan en la de otro mediante rieles de stablecoins.
POST
/
v2
/
order
/
fiat_to_fiat
Crear una orden de pago global
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
}
}La ruta de pago global de fiat a fiat te permite mover dinero entre países sin tocar cripto en la capa de aplicación: VelaFi gestiona internamente los tramos de on-ramp y off-ramp sobre rieles de stablecoins. Configuras tanto el tramo de on-ramp (donde se cobran los fondos) como el tramo de off-ramp (donde se entregan los fondos) en una sola llamada a la API. Fija el monto del lado del on-ramp (
onRampFiatAmount) o del lado del off-ramp (offRampFiatAmount); si envías ambos, onRampFiatAmount tiene prioridad. Un quoteId de la API de cotización fiat/fiat fija el tipo de cambio entre monedas.
Endpoint
POST https://api.velafi.com/v2/order/fiat_to_fiat
Usa
https://api-test.velafi.com/v2/order/fiat_to_fiat para pruebas en sandbox.Headers de la solicitud
| Header | Valor |
|---|---|
X-BH-TOKEN | Tu token de GET /v2/token/generate |
Content-Type | application/json |
Parámetros del cuerpo de la solicitud
Tramo de on-ramp
string
requerido
Nombre completo del país donde se cobra el fiat (por ejemplo,
"Mexico").string
requerido
Código de moneda fiat ISO 4217 en el que paga el remitente (por ejemplo,
"MXN").integer
requerido
ID numérico del método de pago para cobrar el fiat del on-ramp. Consulta los IDs de métodos de pago para ver los valores admitidos.
integer
requerido
ID del comercio para el tramo de on-ramp. Las solicitudes sin un comercio de on-ramp válido se rechazan.
decimal
Monto de fiat que paga el remitente (por ejemplo,
1000.00). Proporciona onRampFiatAmount u offRampFiatAmount; si envías ambos, onRampFiatAmount tiene prioridad.string
Alias de la cuenta virtual que se usa para el depósito fiat del on-ramp.
Tramo de off-ramp
string
requerido
Nombre completo del país donde se entrega el fiat (por ejemplo,
"Argentina").string
requerido
Código de moneda fiat ISO 4217 que recibe el beneficiario (por ejemplo,
"ARS").integer
requerido
ID numérico del método de pago de usuario del beneficiario que recibe el fiat del off-ramp. Debe ser un
userPaymentId válido devuelto por GET /v2/payments.integer
requerido
ID del comercio para el tramo de off-ramp. Las solicitudes sin un comercio de off-ramp válido se rechazan.
decimal
Monto de fiat que recibe el beneficiario (por ejemplo,
55000.00). Se ignora cuando también se envía onRampFiatAmount con un valor de al menos 0.01.Parámetros compartidos
string
Tu propio ID de referencia de la orden. Usa como máximo 40 caracteres. Debe ser único entre todas las órdenes
fiat_to_fiat de tu cuenta; una segunda solicitud de creación con el mismo clientId se rechaza. Se devuelve en las respuestas de Obtener orden y Listar órdenes. Consulta Idempotencia y reintentos.string
Nota opcional de texto libre adjunta a la orden.
string
ID de cotización de la API de cotización para fijar el tipo de cambio entre monedas.
object
Campos adicionales específicos del pago para ciertos métodos de pago.
Mostrar campos de inFieldJson
Mostrar campos de inFieldJson
string
Código de banco obligatorio cuando
onRampPaymentId es 141 (transferencia bancaria colombiana). Consulta Códigos de bancos colombianos.Campos de la respuesta
integer
Código de estado de la respuesta.
200 indica éxito.string
Mensaje de respuesta legible.
object
Objeto con el resultado de la orden.
Mostrar campos de data
Mostrar campos de data
integer
El ID numérico único de la orden creada. Úsalo para obtener el estado completo de la orden y las instrucciones de pago.
Ejemplo
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
}
}
Obtén el estado detallado de las órdenes de fiat a fiat con
GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_fiat. La respuesta incluye objetos de información de pago separados para el on-ramp y el off-ramp, y un conjunto de códigos de estado propio (por ejemplo, 41 pago entrante pendiente, 51 pago saliente pendiente, 60 completada; consulta Estados de las órdenes).Idempotencia y reintentos
UsaclientId para que la creación de órdenes se pueda reintentar de forma segura.
clientIdes opcional. Usa como máximo 40 caracteres. Debe ser único entre todas las órdenesfiat_to_fiatde tu cuenta, para todos tus comercios.- Una solicitud de creación que reutiliza un
clientIdexistente se rechaza con un error de envío repetido y no se crea ninguna orden nueva. - Un
clientIdqueda vinculado a su orden de forma permanente, incluso después de que la orden se cancela. Usa unclientIdnuevo para cada orden nueva. GET /v2/order/detailbusca las órdenesfiat_to_fiatsolo pororderId. Para encontrar una orden porclientId, lista las órdenes recientes conGET /v2/orders?orderType=fiat_to_fiaty busca la coincidencia en el campoclientId.
clientId en la lista de órdenes. Si la orden está ahí, no la vuelvas a crear. Si no está, reintenta con el mismo clientId: si la primera solicitud sí creó la orden mientras tanto, el reintento se rechaza como duplicado en lugar de crear una segunda orden.
Un
quoteId puede quedar consumido por una solicitud de creación que luego se rechaza. Solicita una nueva cotización antes de reintentar.⌘I
Crear una orden de pago global
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
}
}