Create an On-Ramp Order

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
  }
}

The fiat-to-crypto on-ramp converts local fiat currency into cryptocurrency for your user. Specify the source fiat, the target crypto, and the payment method via paymentId. Fix the order amount in either fiat (fiatAmount) or crypto (cryptoAmount); if you send both, fiatAmount takes precedence. To lock the rate, pass a quoteId from the Quote API; without one, the order is priced at the current rate when it is created. The response returns an orderId you can use to track the order through its lifecycle via the Get Order and List Orders endpoints.

Endpoint

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

Use https://api-test.velafi.com/v2/order/fiat_to_crypto for sandbox testing.

Request Headers

Header	Value
`X-BH-TOKEN`	Your token from `GET /v2/token/generate`
`Content-Type`	`application/json`

Request Body Parameters

string

required

Full country name for the on-ramp (e.g., "Mexico", "Brazil"). Must match the country supported by the chosen paymentId.

string

required

Ticker symbol of the target cryptocurrency (e.g., "USDT", "USDC", "BTC").

string

required

ISO 4217 fiat currency code the user pays with (e.g., "MXN", "BRL", "COP").

integer

required

Numeric ID of the payment method used for the fiat deposit. See the Payment Method IDs table in the Payment Templates reference.

string

Your own order reference ID, up to 40 characters. It must be unique across all fiat_to_crypto and crypto_to_fiat orders on your account; a second create request with the same clientId is rejected. It is returned in Get Order responses and can be used instead of orderId to look the order up. See Idempotency and retries.

integer

required

Numeric ID of the merchant the order belongs to. Requests without a valid merchantId are rejected.

decimal

Amount of fiat currency the user pays (e.g., 1000.00). Provide fiatAmount or cryptoAmount; if you send both, fiatAmount takes precedence.

decimal

Amount of cryptocurrency the user receives (e.g., 46.73). Ignored when a positive fiatAmount is also sent.

string

Optional free-text note attached to the order.

string

Alias of the virtual account to use for the fiat deposit. Required for virtual-account-based payment methods.

string

Quote ID from the Quote API to lock in a specific exchange rate. Omit to use the live spot rate.

object

Additional payment-specific fields required for certain payment methods.

Show inFieldJson fields

string

Code of the payer’s bank, required when paymentId is 141 (PSE). PSE uses its own bank list, which is not the same as the Colombian Bank Codes table used for beneficiaries.

Show PSE bank codes

Code	Bank
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

Response Fields

integer

Response status code. 200 indicates success.

string

Human-readable response message.

object

Order result object.

Show data fields

integer

The unique numeric ID of the created order. Use this to retrieve order status and details.

Example

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
  }
}

After creating the order, poll GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto to monitor its status. A new order starts in status: 40 (pending payment), or in 10, 11, or 31 when compliance review or supporting documents are required. Orders on automatic payment methods move to status: 50 (paid) through VelaFi’s bank integration. For manual payment methods, call POST /v2/order/confirm after the transfer is sent to mark the order as paid.

Idempotency and retries

Use clientId to make order creation safe to retry.

clientId is optional. When you send it, it must be at most 40 characters and unique on your account across all fiat_to_crypto and crypto_to_fiat orders, for all of your merchants.
A create request that reuses an existing clientId is rejected with a repeated-submission error, and no new order is created. The response does not return the original order; look it up instead.
A clientId stays bound to its order permanently, including after the order is canceled. Use a new clientId for a new order.
Look up an order by clientId with GET /v2/order/detail?orderType=fiat_to_crypto&clientId={clientId}.

If a create request times out or returns no response:

Call GET /v2/order/detail with the same orderType and clientId.
If the order is found, the original request succeeded. Do not create it again.
If it is not found, retry with the same clientId. If the first request did create the order in the meantime, the retry is rejected as a duplicate instead of creating a second order.

A quoteId can be consumed by a create request that is then rejected. Request a new quote before you retry.

⌘I

Create an On-Ramp Order

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
  }
}

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Create an On-Ramp Order

Endpoint

Request Headers

Request Body Parameters

Response Fields

Example

Idempotency and retries

​Endpoint

​Request Headers

​Request Body Parameters

​Response Fields

​Example

​Idempotency and retries

Endpoint

Request Headers

Request Body Parameters

Response Fields

Example

Idempotency and retries