Órdenes
Crear una orden de off-ramp
Crea una orden de off-ramp de cripto a fiat. La cripto se debita del saldo en cripto del comercio y el fiat local se paga a un beneficiario registrado.
POST
/
v2
/
order
/
crypto_to_fiat
Crear una orden de off-ramp
curl --request POST \
--url https://api-test.velafi.com/v2/order/crypto_to_fiat \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"country": "<string>",
"crypto": "<string>",
"fiat": "<string>",
"userPaymentId": 123,
"clientId": "<string>",
"merchantId": 123,
"cryptoAmount": 123,
"fiatAmount": 123,
"remark": "<string>",
"quoteId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/order/crypto_to_fiat"
payload = {
"country": "<string>",
"crypto": "<string>",
"fiat": "<string>",
"userPaymentId": 123,
"clientId": "<string>",
"merchantId": 123,
"cryptoAmount": 123,
"fiatAmount": 123,
"remark": "<string>",
"quoteId": "<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({
country: '<string>',
crypto: '<string>',
fiat: '<string>',
userPaymentId: 123,
clientId: '<string>',
merchantId: 123,
cryptoAmount: 123,
fiatAmount: 123,
remark: '<string>',
quoteId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/order/crypto_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/crypto_to_fiat")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"country\": \"<string>\",\n \"crypto\": \"<string>\",\n \"fiat\": \"<string>\",\n \"userPaymentId\": 123,\n \"clientId\": \"<string>\",\n \"merchantId\": 123,\n \"cryptoAmount\": 123,\n \"fiatAmount\": 123,\n \"remark\": \"<string>\",\n \"quoteId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": 123
}
}El off-ramp de cripto a fiat permite a tus usuarios convertir criptomonedas en fiat local, que luego se paga al beneficiario identificado por
Para una orden
userPaymentId. Antes de llamar a este endpoint, asegúrate de que el beneficiario de destino se haya registrado mediante POST /v2/payments y tenga status: 1 (válido). Indica el monto en cripto (cryptoAmount) o en fiat (fiatAmount); si envías ambos, fiatAmount tiene prioridad. Para fijar el tipo de cambio, envía un quoteId; sin él, la orden se cotiza al tipo de cambio vigente al momento de crearla. La cripto se toma del saldo en cripto del comercio (consulta Fondeo de la orden).
Endpoint
POST https://api.velafi.com/v2/order/crypto_to_fiat
Usa
https://api-test.velafi.com/v2/order/crypto_to_fiat para pruebas en sandbox.Encabezados de la solicitud
| Encabezado | Valor |
|---|---|
X-BH-TOKEN | Tu token de GET /v2/token/generate |
Content-Type | application/json |
Parámetros del cuerpo de la solicitud
string
requerido
Nombre completo del país del off-ramp (p. ej.,
"Mexico", "Argentina"). Debe coincidir con el país asociado al userPaymentId elegido.string
requerido
Símbolo de la criptomoneda que quieres convertir (p. ej.,
"USDT", "USDC").string
requerido
Código ISO 4217 de la moneda fiat que recibirá el beneficiario (p. ej.,
"MXN", "ARS", "BRL").integer
requerido
ID numérico del beneficiario (método de pago del usuario) que recibirá el pago en fiat. Obtenlo de
GET /v2/payments.string
Tu propio ID de referencia de la orden, de hasta 40 caracteres. Debe ser único entre todas las órdenes
fiat_to_crypto y crypto_to_fiat de tu cuenta; una segunda solicitud de creación con el mismo clientId se rechaza. Se devuelve en las respuestas de Consultar orden y puede usarse en lugar de orderId para buscar la orden. Consulta Idempotencia y reintentos.integer
requerido
ID numérico del comercio al que pertenece la orden. La cripto se debita del saldo de este comercio. Las solicitudes sin un
merchantId válido se rechazan.decimal
Monto de criptomoneda que quieres convertir (p. ej.,
1000.00). Se ignora cuando también se envía un fiatAmount positivo.decimal
Monto en moneda fiat que debe recibir el beneficiario (p. ej.,
21000.00). Envía fiatAmount o cryptoAmount; si envías ambos, fiatAmount tiene prioridad.string
Nota opcional de texto libre adjunta a la orden.
string
ID de cotización de la API de cotizaciones para fijar un tipo de cambio específico. Omítelo para usar el tipo de cambio spot en vivo.
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
ID numérico único de la orden creada. Úsalo para consultar el estado y los detalles de la orden.
Ejemplo
curl -X POST "https://api.velafi.com/v2/order/crypto_to_fiat" \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"country": "Mexico",
"clientId": "my-offramp-2024-001",
"merchantId": 3,
"crypto": "USDT",
"fiat": "MXN",
"cryptoAmount": 1000.00,
"userPaymentId": 91,
"remark": "Payout to supplier",
"quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"orderId": 1123123123
}
}
Fondeo de la orden
La cripto de una orden de off-ramp proviene del saldo en cripto del comercio para elcrypto y el merchantId de la solicitud. Consulta el saldo con Saldo en cripto y recárgalo mediante la dirección de depósito del comercio.
- El saldo cubre la orden: VelaFi debita la cripto del saldo al crear la orden.
- El saldo es insuficiente: la solicitud se rechaza con un error de saldo insuficiente, a menos que tu cuenta tenga habilitado el off-ramp con fondeo posterior (la habilitación puede variar según la moneda fiat).
Con el off-ramp con fondeo posterior habilitado, una orden sin fondos suficientes espera en
status: 32 (en espera del depósito de cripto). Si la orden primero necesita revisión de cumplimiento (status: 10 u 11), pasa a 32 una vez aprobada. Mientras está en 32, el detalle de la orden devuelve orderExpireTimestamp, la fecha límite de fondeo como marca de tiempo Unix en segundos. VelaFi revisa el saldo del comercio cada minuto; cuando varias órdenes esperan sobre el mismo comercio y la misma cripto, el saldo se aplica a ellas de la más antigua a la más reciente. Cuando el saldo cubre una orden, VelaFi debita la cripto y la orden pasa a status: 40, o a 31 si se requieren documentos de soporte. Si la fecha límite vence antes, la orden se cancela (status: 70).crypto_to_fiat en status: 50 (pagada), POST /v2/order/confirm completa la orden (status: 60).
Idempotencia y reintentos
UsaclientId para que la creación de órdenes se pueda reintentar de forma segura.
clientIdes opcional. Si lo envías, debe tener como máximo 40 caracteres y ser único en tu cuenta entre todas las órdenesfiat_to_cryptoycrypto_to_fiat, 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 una nueva orden. La respuesta no devuelve la orden original; búscala por separado. - Un
clientIdqueda asociado a su orden de forma permanente, incluso después de que la orden se cancela. Usa unclientIdnuevo para cada orden nueva. - Busca una orden por
clientIdconGET /v2/order/detail?orderType=crypto_to_fiat&clientId={clientId}.
- Llama a
GET /v2/order/detailcon el mismoorderTypeyclientId. - Si encuentras la orden, la solicitud original fue exitosa. No la vuelvas a crear.
- Si no la encuentras, 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 consumirse en una solicitud de creación que luego se rechaza. Solicita una nueva cotización antes de reintentar.⌘I
Crear una orden de off-ramp
curl --request POST \
--url https://api-test.velafi.com/v2/order/crypto_to_fiat \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"country": "<string>",
"crypto": "<string>",
"fiat": "<string>",
"userPaymentId": 123,
"clientId": "<string>",
"merchantId": 123,
"cryptoAmount": 123,
"fiatAmount": 123,
"remark": "<string>",
"quoteId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/order/crypto_to_fiat"
payload = {
"country": "<string>",
"crypto": "<string>",
"fiat": "<string>",
"userPaymentId": 123,
"clientId": "<string>",
"merchantId": 123,
"cryptoAmount": 123,
"fiatAmount": 123,
"remark": "<string>",
"quoteId": "<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({
country: '<string>',
crypto: '<string>',
fiat: '<string>',
userPaymentId: 123,
clientId: '<string>',
merchantId: 123,
cryptoAmount: 123,
fiatAmount: 123,
remark: '<string>',
quoteId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/order/crypto_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/crypto_to_fiat")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"country\": \"<string>\",\n \"crypto\": \"<string>\",\n \"fiat\": \"<string>\",\n \"userPaymentId\": 123,\n \"clientId\": \"<string>\",\n \"merchantId\": 123,\n \"cryptoAmount\": 123,\n \"fiatAmount\": 123,\n \"remark\": \"<string>\",\n \"quoteId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.orderId": 123
}
}