Set up
- Switch the dashboard to Sandbox.
- Create a
sk_test_key. See Get your API keys. - Add a sandbox webhook endpoint. See Webhooks.
- Point your code at
https://sandbox.api.payvehq.com. See Environments.
Fund your sandbox wallet
A payout needs a balance. To get one:- Create a
bank_transferorvirtual_accountpay-in. Note the account number inauthorization. - Open the Payment simulator in the dashboard and choose Fund virtual account.
- Enter the account number and an amount, then select Send transfer.
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
The happy path
- Quote, payout,
payout.successful. - [ ] Pay-in, simulated transfer,payin.successful, wallet credited. - [ ] Conversion,conversion.successful, both balances changed.
Failures
Failures
- A payout to
0000000000ends asfailed, your user is told, and your wallet balance is restored. - [ ] A payout larger than your balance returns422 wallet_insufficient_funds. - [ ] A declined card (0000) is shown to the payer as declined. - [ ] An expired quote returns422 quote_expiredand your code asks for a new one.
Idempotency
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 get422 idempotency_key_reused. - [ ] Kill your process after sending and retry on restart with the stored key. Still one payout.
Webhooks
Webhooks
- A request with a wrong signature is rejected with
401. - [ ] The same event delivered twice is processed once. - [ ] Make your endpoint return500, then fix it. The event arrives on a retry. - [ ] An unknown event type gets a200.
Amounts
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.

