Sandbox

The VelaFi sandbox is an isolated test environment that mirrors the production API’s structure and behavior using entirely simulated data. You can create orders, query accounts, and exercise the full request/response cycle without moving real money, verifying real identities, or affecting any live merchant accounts. It is the recommended starting point for any new integration and a safe place to validate changes before deploying them to production.

Sandbox Base URL

Point your HTTP client at the following base URL to reach the sandbox:

https://api-test.velafi.com

All production endpoints are available under this base URL with the same path structure. For example, to retrieve fiat trading pairs in the sandbox:

curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols

This endpoint is public, so it needs no token. Endpoints that act on your account do: see Authentication.

Getting Sandbox Credentials

Sandbox API keys are provisioned separately from production keys and are not generated through the dashboard. To obtain your sandbox API key and API secret, contact the VelaFi team directly:

Email: contact@velafi.com

You do not need to complete KYC/KYB or create a merchant account to access the sandbox. The VelaFi team will provision a pre-configured test account with simulated user and merchant data ready to use.

Once you receive your credentials, use them to get a token from GET /v2/token/generate and include it in the X-BH-TOKEN header of every request, exactly as you would in production:

X-BH-TOKEN: YOUR_SANDBOX_TOKEN

Sandbox vs. Production

The table below summarizes the key behavioral differences between the two environments. Use this as a checklist when deciding which environment is appropriate for a given activity.

Feature	Sandbox	Production
KYC / KYB required	No — pre-configured test accounts provided	Yes — full identity verification required
API key creation	Not required — credentials provided by VelaFi	Required — generated through the dashboard with 2FA
User and account data	Virtual and simulated; not linked to real individuals	Real data tied to verified merchants and users
Fund transfers	No real funds move; all transactions are simulated	Real funds transferred via live payment rails
Webhook callbacks	Not triggered — no callback events are fired	Triggered on order status changes
Base URL	`https://api-test.velafi.com`	`https://api.velafi.com`

Never use production API keys against the sandbox base URL, or sandbox credentials against the production base URL. Keep the two sets of credentials strictly separated in your environment configuration.

Example: Retrieve Fiat Trading Pairs

The following request demonstrates a complete sandbox API call. It uses a public endpoint, so it confirms you can reach the sandbox but does not test your credentials.

curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols

import requests

response = requests.get(
    "https://api-test.velafi.com/v2/base/fiat/symbols",
)
print(response.json())

const response = await fetch(
  "https://api-test.velafi.com/v2/base/fiat/symbols",
  {
    method: "GET",
  }
);
const data = await response.json();
console.log(data);

A successful response returns the list of supported fiat trading pairs available in the test environment:

{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "symbol": "ARS_USDT",
      "base_currency": "ARS",
      "quote_currency": "USDT",
      "status": "active"
    },
    {
      "symbol": "MXN_USDT",
      "base_currency": "MXN",
      "quote_currency": "USDT",
      "status": "active"
    }
  ]
}

Run through your entire on-ramp, off-ramp, and global payment order flows in the sandbox before switching to production. Because webhook callbacks are not triggered in sandbox, poll the order status endpoint manually to verify state transitions during testing.

Recommended Testing Workflow

Work through the following sequence in the sandbox to validate your integration end to end before going live:

Confirm credentials

Get a token from GET https://api-test.velafi.com/v2/token/generate with your sandbox API key and secret, then call GET /v2/user/account with it. A successful response confirms that your key, secret, IP whitelist, and API access are all set up.

Test on-ramp order creation

Create a fiat-to-crypto order using simulated merchant and account data. Verify that the system returns an order_id and that you can retrieve the order by ID.

Test off-ramp order creation

Create a crypto-to-fiat order and confirm the response includes the expected settlement details and beneficiary information.

Test global payment order creation

Create a fiat-to-fiat order with a sender and recipient merchant configured for different fiat currencies. Confirm the order status progresses as expected.

Switch to production

Replace the sandbox base URL with https://api.velafi.com, swap in your production API key and secret, and get tokens from the production host. Re-run a smoke test against the production /v2/user/account endpoint to confirm the switch.

Sandbox Testing Tools

The sandbox has two endpoints that simulate incoming deposits, so you can fund test merchants without moving real money. They exist only on https://api-test.velafi.com. On https://api.velafi.com they return 404. Both accept GET or POST, with the parameters sent as query parameters.

Simulate a Fiat Deposit

https://api-test.velafi.com/v2/platform/test/deposit Simulates an incoming bank deposit to a merchant’s activated fiat account.

number

required

ID of the merchant to credit.

string

required

Fiat currency code, for example MXN.

number

required

Amount to deposit. Must be greater than 0.

number

required

Payment method ID of the merchant’s activated fiat account for this currency.

string

Alias of a virtual account under the same merchantId, fiat and paymentId. When set, the deposit goes to that virtual account.

Common failure messages:

The merchant has not activated the corresponding fiat currency account. — the merchant has no active account for this fiat and paymentId.
The depositAlias invalid. — no virtual account matches depositAlias.
This method of currency recharge is not currently supported. — this payment method has no deposit simulator.

cURL

curl -G https://api-test.velafi.com/v2/platform/test/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "fiat=MXN" \
  --data-urlencode "fiatAmount=1000" \
  --data-urlencode "paymentId=105"

Simulate a Crypto Deposit

https://api-test.velafi.com/v2/platform/test/crypto/deposit Adds test crypto funds to a merchant’s wallet.

number

required

ID of an approved merchant.

string

required

One of USDT, USDC, BTC, MMXN, COPM or MXNB. Other values return {"code":500, "msg":"crypto is invalid"}.

number

required

Amount to add. Must be greater than 0.

On success the response code is 200.

cURL

curl -G https://api-test.velafi.com/v2/platform/test/crypto/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "crypto=USDT" \
  --data-urlencode "amount=500"

The simulators only cover successful deposits. They cannot produce a failed or returned deposit.

Get Started

Core Concepts

Guides

Reference

Sandbox Base URL

Getting Sandbox Credentials

Sandbox vs. Production

Example: Retrieve Fiat Trading Pairs

Recommended Testing Workflow

Sandbox Testing Tools

Simulate a Fiat Deposit

Simulate a Crypto Deposit

Next Steps

Quickstart

API Reference

​Sandbox Base URL

​Getting Sandbox Credentials

​Sandbox vs. Production

​Example: Retrieve Fiat Trading Pairs

​Recommended Testing Workflow

​Sandbox Testing Tools

​Simulate a Fiat Deposit

​Simulate a Crypto Deposit

​Next Steps

Quickstart

API Reference

Sandbox Base URL

Getting Sandbox Credentials

Sandbox vs. Production

Example: Retrieve Fiat Trading Pairs

Recommended Testing Workflow

Sandbox Testing Tools

Simulate a Fiat Deposit

Simulate a Crypto Deposit

Next Steps