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

# Sandbox

> Test mode for every endpoint: the same requests, responses and signed webhooks, with no bank, blockchain or real money involved.

## How it works

Use a `fpay_test_` key and every call goes to the sandbox. Responses include `"livemode": false`, and webhooks carry the header `x-flipeetpay-mode: sandbox`.

* Your sandbox balance starts at 10,000 USDC and 10,000 USDT, separate from your live balance.
* Deposits wait for you, as a real customer would. Complete or fail them with [Simulate an outcome](https://docs.flipeet.io/api-reference/sandbox/simulate-an-outcome.md).
* Withdrawals settle on their own after about 3 seconds.
* Orders and bank deposits are priced at fixed test rates, so your tests give the same numbers every time.

| Currency | Test rate (per 1 USDC or USDT) |
| - | - |
| NGN | 1,500 |
| GHS | 15 |
| KES | 129 |
| UGX | 3,700 |
| TZS | 2,600 |
| XOF, XAF | 600 |

> [!NOTE]
>
> Quotes, rates and the bank list return live data even with a test key, so you can build against real numbers. Orders, deposits and payouts are what's simulated.

## Simulate a payment

Pass the reference of any sandbox deposit, withdrawal or ramp order, or a checkout's `txRef`, with `success` or `failed`. For deposits you can say how much the customer paid, to test under- and over-payment.

```bash cURL theme={null}
curl -X POST "https://api.pay.flipeet.io/api/v1/sandbox/simulate" \
  -H "x-api-key: $FLIPEET_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reference": "inv_2201",
  "outcome": "success",
  "amount": 100
}'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pay.flipeet.io/api/v1/sandbox/simulate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reference": "inv_2201",
    "outcome": "success",
    "amount": 100
  }),
});
const { data } = await response.json();
```

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

response = requests.post(
    "https://api.pay.flipeet.io/api/v1/sandbox/simulate",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
    json={
        "reference": "inv_2201",
        "outcome": "success",
        "amount": 100
    },
)
data = response.json()["data"]
```

The payment moves to `completed` or `failed`, your sandbox balance changes as it would live (fees included), and the webhook goes out. Each payment settles once; a second call gets `409`.

## Test values

Like test card numbers, these make a call fail so you can test your error handling.

| Use | To get |
| - | - |
| A wallet address ending in `dead` | A failed crypto withdrawal, refunded to your balance |
| Account number `0000000000` | A failed bank withdrawal, refunded to your balance |
| An amount above your balance | `400` with an insufficient balance message |
| A reference you've already used | `409` conflict |

## Checkout in the sandbox

A test checkout page shows a sandbox banner with **Complete payment** and **Fail payment** buttons, so you can click through your whole flow, including the redirect. It never takes real funds. Failing a test checkout sends `checkout.failed`, so you can test that path too.

## Add test funds

```bash cURL theme={null}
curl -X POST "https://api.pay.flipeet.io/api/v1/sandbox/balance/top-up" \
  -H "x-api-key: $FLIPEET_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "asset": "usdc",
  "amount": 5000
}'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pay.flipeet.io/api/v1/sandbox/balance/top-up", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "asset": "usdc",
    "amount": 5000
  }),
});
const { data } = await response.json();
```

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

response = requests.post(
    "https://api.pay.flipeet.io/api/v1/sandbox/balance/top-up",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
    json={
        "asset": "usdc",
        "amount": 5000
    },
)
data = response.json()["data"]
```


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