Create an Off-Ramp Order

POST

order

crypto_to_fiat

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

The crypto-to-fiat off-ramp lets your users convert cryptocurrency into local fiat, which is then paid out to the beneficiary identified by userPaymentId. Before calling this endpoint, ensure the target beneficiary has been registered via POST /v2/payments and has status: 1 (valid). Specify the amount in either crypto (cryptoAmount) or fiat (fiatAmount); if you send both, fiatAmount takes precedence. To lock the rate, pass a quoteId; without one, the order is priced at the current rate when it is created. The crypto is taken from the merchant’s crypto balance (see Funding the order).

Endpoint

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

Use https://api-test.velafi.com/v2/order/crypto_to_fiat 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 off-ramp (e.g., "Mexico", "Argentina"). Must match the country associated with the chosen userPaymentId.

string

required

Ticker symbol of the cryptocurrency to convert (e.g., "USDT", "USDC").

string

required

ISO 4217 fiat currency code the beneficiary will receive (e.g., "MXN", "ARS", "BRL").

integer

required

The numeric ID of the beneficiary (user payment method) to receive the fiat payout. Retrieve this from GET /v2/payments.

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. The crypto is debited from this merchant’s balance. Requests without a valid merchantId are rejected.

decimal

Amount of cryptocurrency to convert (e.g., 1000.00). Ignored when a positive fiatAmount is also sent.

decimal

Amount of fiat currency the beneficiary should receive (e.g., 21000.00). Provide fiatAmount or cryptoAmount; if you send both, fiatAmount takes precedence.

string

Optional free-text note attached to the order.

string

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

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

Funding the order

The crypto for an off-ramp order comes from the merchant’s crypto balance for the crypto and merchantId in the request. Check the balance with Crypto Balance and top it up through the merchant’s deposit address.

Balance covers the order: VelaFi debits the crypto from the balance when it creates the order.
Balance is too low: the request is rejected with an insufficient-balance error, unless post-funded off-ramp is enabled for your account (enablement can differ by fiat currency).

With post-funded off-ramp enabled, an underfunded order waits in status: 32 (awaiting crypto deposit). If the order first needs compliance review (status: 10 or 11), it moves to 32 once approved. While it is in 32, order detail returns orderExpireTimestamp, the funding deadline as a Unix timestamp in seconds. VelaFi checks the merchant’s balance every minute; when several orders are waiting on the same merchant and crypto, the balance is applied to them oldest first. Once the balance covers an order, VelaFi debits the crypto and the order moves to status: 40, or 31 if supporting documents are required. If the deadline passes first, the order is canceled (status: 70).

For a crypto_to_fiat order in status: 50 (paid), POST /v2/order/confirm completes the order (status: 60).

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=crypto_to_fiat&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 Off-Ramp Order

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

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Create an Off-Ramp Order

Endpoint

Request Headers

Request Body Parameters

Response Fields

Example

Funding the order

Idempotency and retries

​Endpoint

​Request Headers

​Request Body Parameters

​Response Fields

​Example

​Funding the order

​Idempotency and retries

Endpoint

Request Headers

Request Body Parameters

Response Fields

Example

Funding the order

Idempotency and retries