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.
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 to Sandbox.
  2. Create a sk_test_ key. See Get your API keys.
  3. Add a sandbox webhook endpoint. See Webhooks.
  4. Point your code at https://sandbox.api.payvehq.com. See Environments.

Fund your sandbox wallet

A payout needs a balance. To get one:
  1. Create a bank_transfer or virtual_account pay-in. 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.

Name checks

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. In the PIN-then-code flow the simulator accepts any PIN and any code.

Mobile money pay-ins

The phone number decides the outcome. 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. 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

The happy path

  • Quote, payout, payout.successful. - [ ] Pay-in, simulated transfer, payin.successful, wallet credited. - [ ] Conversion, conversion.successful, both balances changed.
  • 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.
  • 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.
  • 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.
  • 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.