Crear una orden de on-ramp

POST

order

fiat_to_crypto

curl --request POST \
  --url https://api-test.velafi.com/v2/order/fiat_to_crypto \
  --header 'Content-Type: application/json' \
  --header 'X-BH-TOKEN: <api-key>' \
  --data '
{
  "country": "<string>",
  "crypto": "<string>",
  "fiat": "<string>",
  "paymentId": 123,
  "clientId": "<string>",
  "merchantId": 123,
  "fiatAmount": 123,
  "cryptoAmount": 123,
  "remark": "<string>",
  "depositAlias": "<string>",
  "quoteId": "<string>",
  "inFieldJson": {
    "inFieldJson.bank": "<string>"
  }
}
'

import requests

url = "https://api-test.velafi.com/v2/order/fiat_to_crypto"

payload = {
    "country": "<string>",
    "crypto": "<string>",
    "fiat": "<string>",
    "paymentId": 123,
    "clientId": "<string>",
    "merchantId": 123,
    "fiatAmount": 123,
    "cryptoAmount": 123,
    "remark": "<string>",
    "depositAlias": "<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({
    country: '<string>',
    crypto: '<string>',
    fiat: '<string>',
    paymentId: 123,
    clientId: '<string>',
    merchantId: 123,
    fiatAmount: 123,
    cryptoAmount: 123,
    remark: '<string>',
    depositAlias: '<string>',
    quoteId: '<string>',
    inFieldJson: {'inFieldJson.bank': '<string>'}
  })
};

fetch('https://api-test.velafi.com/v2/order/fiat_to_crypto', 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_crypto")
  .header("X-BH-TOKEN", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"<string>\",\n  \"crypto\": \"<string>\",\n  \"fiat\": \"<string>\",\n  \"paymentId\": 123,\n  \"clientId\": \"<string>\",\n  \"merchantId\": 123,\n  \"fiatAmount\": 123,\n  \"cryptoAmount\": 123,\n  \"remark\": \"<string>\",\n  \"depositAlias\": \"<string>\",\n  \"quoteId\": \"<string>\",\n  \"inFieldJson\": {\n    \"inFieldJson.bank\": \"<string>\"\n  }\n}")
  .asString();

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": 123
  }
}

El on-ramp de fiat a cripto convierte moneda fiat local en criptomoneda para tu usuario. Especifica la moneda fiat de origen, la cripto de destino y el método de pago mediante paymentId. Fija el monto de la orden en fiat (fiatAmount) o en cripto (cryptoAmount); si envías ambos, fiatAmount tiene prioridad. Para fijar el tipo de cambio, envía un quoteId de la API de cotizaciones; sin él, la orden se valúa al tipo de cambio vigente al momento de crearla. La respuesta devuelve un orderId que puedes usar para dar seguimiento a la orden durante todo su ciclo de vida mediante los endpoints Obtener orden y Listar órdenes.

Endpoint

POST https://api.velafi.com/v2/order/fiat_to_crypto

Usa https://api-test.velafi.com/v2/order/fiat_to_crypto para hacer pruebas en el 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 on-ramp (por ejemplo, "Mexico", "Brazil"). Debe coincidir con el país admitido por el paymentId elegido.

string

requerido

Símbolo (ticker) de la criptomoneda de destino (por ejemplo, "USDT", "USDC", "BTC").

string

requerido

Código ISO 4217 de la moneda fiat con la que paga el usuario (por ejemplo, "MXN", "BRL", "COP").

integer

requerido

ID numérico del método de pago usado para el depósito en fiat. Consulta la tabla de IDs de métodos de pago en la referencia de plantillas de pago.

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 Obtener orden y se puede usar en lugar de orderId para buscar la orden. Consulta Idempotencia y reintentos.

integer

requerido

ID numérico del comercio al que pertenece la orden. Las solicitudes sin un merchantId válido se rechazan.

decimal

Monto de moneda fiat que paga el usuario (por ejemplo, 1000.00). Envía fiatAmount o cryptoAmount; si envías ambos, fiatAmount tiene prioridad.

decimal

Monto de criptomoneda que recibe el usuario (por ejemplo, 46.73). Se ignora cuando también se envía un fiatAmount positivo.

string

Nota opcional de texto libre adjunta a la orden.

string

Alias de la cuenta virtual que se usará para el depósito en fiat. Obligatorio para los métodos de pago basados en cuentas virtuales.

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 tiempo real.

object

Campos adicionales específicos del pago, requeridos por ciertos métodos de pago.

Mostrar Campos de inFieldJson

string

Código del banco del pagador, obligatorio cuando paymentId es 141 (PSE). PSE usa su propia lista de bancos, que no es la misma que la tabla de Códigos de bancos de Colombia que se usa para los beneficiarios.

Mostrar Códigos de bancos de PSE

Código	Banco
1001	BANCO DE BOGOTA
1002	BANCO POPULAR
1006	ITAU
1007	BANCOLOMBIA
1009	CITIBANK
1012	BANCO GNB SUDAMERIS
1013	BBVA COLOMBIA
1019	DAVIBANK
1023	BANCO DE OCCIDENTE
1032	BANCO CAJA SOCIAL BCSC SA
1040	BANCO AGRARIO
1047	BANCO MUNDO MUJER
1051	BANCO DAVIVIENDA SA
1052	BANCO AV VILLAS
1059	BANCO DE LAS MICROFINANZAS - BANCAMIA S.A.
1060	BANCO PICHINCHA
1061	BANCOOMEVA
1062	BANCO FALABELLA S.A.
1063	BANCO FINANDINA S.A.
1065	BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A
1066	BANCO COOPERATIVO COOPCENTRAL
1069	BANCO SERFINANZA S.A
1070	LULO BANK S.A.
1071	BANCO J.P. MORGAN COLOMBIA S.A.
1097	Dale
1121	FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO
1283	COOPERATIVA FINANCIERA DE ANTIOQUIA
1286	JFK COOPERATIVA FINANCIERA
1289	COOTRAFA COOPERATIVA FINANCIERA
1292	CONFIAR COOPERATIVA FINANCIERA
1303	BANCO UNION S.A
1370	COLTEFINANCIERA S.A
1507	NEQUI
1551	DAVIPLATA
1558	BAN100 S.A
1637	IRIS
1801	MOVII
1802	DING TECNIPAGOS SA
1804	UALA
1808	BOLD CF
1809	NU COLOMBIA
1811	RAPPIPAY
1812	COINK
1814	GLOBAL66
1815	Alianza fiduciaria
1816	Crezcamos

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

integer

ID numérico único de la orden creada. Úsalo para obtener el estado y los detalles de la orden.

Ejemplo

curl -X POST "https://api.velafi.com/v2/order/fiat_to_crypto" \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "Colombia",
    "clientId": "my-order-2024-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "COP",
    "fiatAmount": 100000.00,
    "paymentId": 141,
    "remark": "On-ramp for user #42",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "inFieldJson": {
      "bank": "1001"
    }
  }'

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": 1123123123
  }
}

Después de crear la orden, consulta periódicamente GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto para monitorear su estado. Una orden nueva inicia en status: 40 (pago pendiente), o en 10, 11 o 31 cuando se requiere revisión de cumplimiento o documentos de soporte. Las órdenes con métodos de pago automáticos pasan a status: 50 (pagada) mediante la integración bancaria de VelaFi. Para los métodos de pago manuales, llama a POST /v2/order/confirm después de enviar la transferencia para marcar la orden como pagada.

Idempotencia y reintentos

Usa clientId para que la creación de órdenes se pueda reintentar con seguridad.

clientId es opcional. Cuando lo envías, debe tener como máximo 40 caracteres y ser único en tu cuenta entre todas las órdenes fiat_to_crypto y crypto_to_fiat, para todos tus comercios.
Una solicitud de creación que reutiliza un clientId existente se rechaza con un error de envío repetido y no se crea ninguna orden nueva. La respuesta no devuelve la orden original; búscala por separado.
Un clientId queda vinculado a su orden de forma permanente, incluso después de que la orden se cancela. Usa un clientId nuevo para una orden nueva.
Busca una orden por clientId con GET /v2/order/detail?orderType=fiat_to_crypto&clientId={clientId}.

Si una solicitud de creación agota el tiempo de espera o no devuelve respuesta:

Llama a GET /v2/order/detail con el mismo orderType y clientId.
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 se puede consumir en una solicitud de creación que luego se rechaza. Solicita una cotización nueva antes de reintentar.

⌘I

Crear una orden de on-ramp

curl --request POST \
  --url https://api-test.velafi.com/v2/order/fiat_to_crypto \
  --header 'Content-Type: application/json' \
  --header 'X-BH-TOKEN: <api-key>' \
  --data '
{
  "country": "<string>",
  "crypto": "<string>",
  "fiat": "<string>",
  "paymentId": 123,
  "clientId": "<string>",
  "merchantId": 123,
  "fiatAmount": 123,
  "cryptoAmount": 123,
  "remark": "<string>",
  "depositAlias": "<string>",
  "quoteId": "<string>",
  "inFieldJson": {
    "inFieldJson.bank": "<string>"
  }
}
'

import requests

url = "https://api-test.velafi.com/v2/order/fiat_to_crypto"

payload = {
    "country": "<string>",
    "crypto": "<string>",
    "fiat": "<string>",
    "paymentId": 123,
    "clientId": "<string>",
    "merchantId": 123,
    "fiatAmount": 123,
    "cryptoAmount": 123,
    "remark": "<string>",
    "depositAlias": "<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({
    country: '<string>',
    crypto: '<string>',
    fiat: '<string>',
    paymentId: 123,
    clientId: '<string>',
    merchantId: 123,
    fiatAmount: 123,
    cryptoAmount: 123,
    remark: '<string>',
    depositAlias: '<string>',
    quoteId: '<string>',
    inFieldJson: {'inFieldJson.bank': '<string>'}
  })
};

fetch('https://api-test.velafi.com/v2/order/fiat_to_crypto', 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_crypto")
  .header("X-BH-TOKEN", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"<string>\",\n  \"crypto\": \"<string>\",\n  \"fiat\": \"<string>\",\n  \"paymentId\": 123,\n  \"clientId\": \"<string>\",\n  \"merchantId\": 123,\n  \"fiatAmount\": 123,\n  \"cryptoAmount\": 123,\n  \"remark\": \"<string>\",\n  \"depositAlias\": \"<string>\",\n  \"quoteId\": \"<string>\",\n  \"inFieldJson\": {\n    \"inFieldJson.bank\": \"<string>\"\n  }\n}")
  .asString();

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": 123
  }
}

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Crear una orden de on-ramp

Endpoint

Encabezados de la solicitud

Parámetros del cuerpo de la solicitud

Campos de la respuesta

Ejemplo

Idempotencia y reintentos

​Endpoint

​Encabezados de la solicitud

​Parámetros del cuerpo de la solicitud

​Campos de la respuesta

​Ejemplo

​Idempotencia y reintentos

Endpoint

Encabezados de la solicitud

Parámetros del cuerpo de la solicitud

Campos de la respuesta

Ejemplo

Idempotencia y reintentos