> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Use the VelaFi sandbox to build and validate your integration against simulated data — no real funds, no KYC, and no risk before you go to production.

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:

```bash theme={null}
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](https://docs.velafi.com/api-reference/authentication.md).

## 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](mailto:contact@velafi.com)

> [!NOTE]
>
> 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:

```http theme={null}
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` |

> [!WARNING]
>
> 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.

```bash cURL theme={null}
curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols
```

```python Python theme={null}
import requests

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

```javascript Node.js theme={null}
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:

```json theme={null}
{
  "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"
    }
  ]
}
```

> [!TIP]
>
> 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:

**1. 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.

**2. 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.

**3. Test off-ramp order creation**

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

**4. 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.

**5. 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.

**merchantId** `number` *required*

ID of the merchant to credit.

**fiat** `string` *required*

Fiat currency code, for example `MXN`.

**fiatAmount** `number` *required*

Amount to deposit. Must be greater than `0`.

**paymentId** `number` *required*

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

**depositAlias** `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.

```bash cURL theme={null}
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.

**merchantId** `number` *required*

ID of an approved merchant.

**crypto** `string` *required*

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

**amount** `number` *required*

Amount to add. Must be greater than `0`.

On success the response `code` is `200`.

```bash cURL theme={null}
curl -G https://api-test.velafi.com/v2/platform/test/crypto/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "crypto=USDT" \
  --data-urlencode "amount=500"
```

> [!NOTE]
>
> The simulators only cover successful deposits. They cannot produce a failed or returned deposit.

***

## Next Steps

> [card] [Quickstart](https://docs.velafi.com/docs/quickstart.md)
>
> Set up your production account and generate your live API key.

> [card] [API Reference](https://docs.velafi.com/api-reference/overview.md)
>
> Browse all available endpoints, parameters, and response schemas.


## Related topics

- [Authentication](https://docs.velafi.com/api-reference/authentication.md)
- [Base URLs](https://docs.velafi.com/api-reference/basic-configuration/api-endpoint.md)
- [Payment Methods](https://docs.velafi.com/docs/payment-methods.md)
- [Changelog](https://docs.velafi.com/docs/changelog.md)
- [Create an API Key](https://docs.velafi.com/docs/guides/creating-api-key.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.