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

# Test in the sandbox

> Simulate success, failure and delay with fixed test values. No real money moves.

The sandbox runs your requests against a simulator instead of real banks. Specific values produce specific outcomes, every time, so you can test each path on purpose.

> [!WARNING]
>
> These values are special **only in the sandbox**. In live they are ordinary account, card and
> phone numbers. Never send a live payout to a test number.

## Set up

1. Switch the [dashboard](https://app.payvehq.com) to **Sandbox**.
2. Create a `sk_test_` key. See [Get your API keys](/get-started/api-keys.md).
3. Add a sandbox webhook endpoint. See [Webhooks](/webhooks/overview.md).
4. Point your code at `https://sandbox.api.payvehq.com`. See [Environments](/get-started/environments.md).

## Fund your sandbox wallet

A payout needs a balance. To get one:

1. Create a `bank_transfer` or `virtual_account` [pay-in](/guides/payins.md). Note the account number in `authorization`.
2. Open the **Payment simulator** in the dashboard and choose **Fund virtual account**.
3. Enter the account number and an amount, then select **Send transfer**.

The pay-in becomes `successful`, your wallet is credited, and you receive `payin.successful`.

## Payouts

The beneficiary's **account number** decides the outcome.

| Account number | Outcome |
| - | - |
| Any other number | Succeeds. `payout.successful` arrives about five seconds later. |
| `0000000000` | Fails at once: the recipient's bank is offline. You get `payout.failed`. |
| `1111111111` | Fails at once: the account does not exist at that bank. You get `payout.failed`. |
| `9999999999` | Succeeds, then the simulator reports a reversal 30 seconds later. |

```bash
curl -X POST "$PAYVE_API_URL/v1/payouts" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: sandbox-fail-test-01" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "amount": 100000,
    "method": "bank_transfer",
    "beneficiary": {
      "type": "bank_account",
      "accountNumber": "0000000000",
      "bankCode": "058",
      "holderName": "Test Offline Bank",
      "country": "NG"
    }
  }'
```

## Name checks

| Account number | `GET /v1/payouts/validate-account` returns |
| - | - |
| Any other number | A made-up name. The same number always gives the same name. |
| `0000000000` | `[Test] Offline Bank Account` |
| `1111111111` | `[Test] Invalid Account` |
| `9999999999` | `[Test] Reversal Account` |
| `2222222222` | An error: the account is blocked. |

The three payout test accounts pass the name check on purpose, so that you can save them and then watch the payout itself fail.

A mobile money number between 9 and 15 digits returns `valid: true` with a made-up name. Anything shorter or longer returns `valid: false`.

## Card pay-ins

Use any card number that passes validation. The **last four digits** decide the outcome. Any expiry date in the future and any three-digit CVV work.

| Card number ends in | Outcome |
| - | - |
| `0000` | Declined: do not honour. |
| `9999` | Declined: insufficient funds. |
| `0001` | Declined: expired card. |
| `3220` | Redirects to a simulated 3-D Secure page. |
| Anything else | Asks for a PIN, then a one-time code, then succeeds. |

In the PIN-then-code flow the simulator accepts any PIN and any code.

## Mobile money pay-ins

The **phone number** decides the outcome.

| Phone number | Outcome |
| - | - |
| `0000000000` | Fails: the account is blocked. |
| `1111111111` | Fails: insufficient funds. |
| `2222222222` | Fails: daily limit exceeded. |
| Anything else | Waits for approval in the simulator. |

Approve or reject a waiting charge from the **Mobile wallet** tab of the Payment simulator.

## Bank transfer and virtual account pay-ins

Use the **Fund virtual account** tab of the Payment simulator to send a transfer into the account a pay-in gave you.

| To test | Do this |
| - | - |
| A correct payment | Send exactly the pay-in's amount. |
| An underpayment | Send less than the amount. |
| An overpayment | Send more than the amount. |
| An expired pay-in | Send nothing, and wait until `authorization.expiresAt` has passed. |

For a payment link, use the test controls on the hosted checkout page. They appear only in the sandbox.

## What to test before you go live

> [accordion] The happy path
>
> * [ ] Quote, payout, `payout.successful`. - \[ ] Pay-in, simulated transfer, `payin.successful`,
>   wallet credited. - \[ ] Conversion, `conversion.successful`, both balances changed.

> [accordion] Failures
>
> * [ ] A payout to `0000000000` ends as `failed`, your user is told, and your wallet balance is
>   restored. - \[ ] A payout larger than your balance returns `422 wallet_insufficient_funds`. - \[ ]
>   A declined card (`0000`) is shown to the payer as declined. - \[ ] An expired quote returns `422
>       quote_expired` and your code asks for a new one.

> [accordion] Idempotency
>
> * [ ] Send the same payout twice with the same key. You get one payout, and the second response
>   carries `Idempotent-Replayed: true`. - \[ ] Send a different body with the same key. You get `422
>       idempotency_key_reused`. - \[ ] Kill your process after sending and retry on restart with the
>   stored key. Still one payout.

> [accordion] Webhooks
>
> * [ ] A request with a wrong signature is rejected with `401`. - \[ ] The same event delivered
>   twice is processed once. - \[ ] Make your endpoint return `500`, then fix it. The event arrives
>   on a retry. - \[ ] An unknown event type gets a `200`.

> [accordion] Amounts
>
> * [ ] Every amount you send is an integer in minor units. - \[ ] Every amount you display is
>   converted from minor units correctly.

## Limits of the sandbox

* Timing is not realistic. Live payouts depend on the bank or operator.
* Names from name checks are made up.
* Rates and fees are for testing. Do not use sandbox figures in a business case.
* A scenario passing in the sandbox proves your code path, not that a live route is switched on for your account. See [Coverage](/essentials/coverage.md).
