Overview
There are two ways to simulate a transaction in sandbox. You can either hit the sandbox API directly and follow the transaction in the merchant dashboard, or use the prepared sandbox environment from inside the documentation.
1. Simulate by Hitting the Sandbox API
- 1
Log In to the Merchant Dashboard
Sign in to the merchant dashboard and switch your account into sandbox mode before creating any test transaction.
- 2
Create a Sandbox API Key
Create a sandbox API key first if you have not done so already.
- 3
Create a Checkout Transaction
Use that sandbox API key to create a checkout transaction from the Checkout API.
- 4
Complete the Transaction
Open the returned checkout page, complete the transaction there, and finish the sandbox payment flow.
- 5
Monitor It on the Dashboard
While you are still in sandbox mode, open the Transactions page on the merchant dashboard and monitor the test transaction there.
2. Simulate from the Prepared Environment
If you want to simulate payment without leaving the documentation, use the prepared sandbox workbench at Sandbox Env. It gives you a guided request builder, prepared test phone scenarios, a live payload preview, direct response inspection, and a recent transactions view tied to your sandbox API key.
- 1
Open Sandbox Env from the Documentation
Open the built-in Sandbox Env page to simulate requests without leaving the docs site.
- 2
Enter Your Sandbox API Key
You must create a sandbox API key from the merchant portal before you can use Sandbox Env. If you have not created one yet, log in at https://merchant.prod.afropays.co/auth/login, switch your account to sandbox mode, and create the key from the portal first.
After that, paste the sandbox API key into the request builder. The same key is used both to send the request and to load recent sandbox transactions.
- 3
Choose the Endpoint and Test Scenario
Select the API endpoint you want to simulate, then choose one of the prepared test phone numbers. Each number maps to a fixed result such as success, failed, or canceled.
The available phone numbers change automatically depending on the selected endpoint family, including separate scenarios for M-Pesa flows.
- 4
Adjust the Editable Request Values
Set the amount, provide a valid callback URL, and make sure the merchant order id is unique for that payment simulation.
For every sandbox payment, you can either enter the merchant order id manually or switch to the auto-generated mode in Sandbox Env so a fresh value is prepared for you.
- 5
Use a Reachable Callback Destination
To receive callbacks, your callbackUrl must point to a reachable endpoint. You can use your own public hosted callback URL, expose a local endpoint during development from Expose Endpoint, or use a mock callback destination from Callback Testing.
- 6
Review the Generated Payload Before Sending
Use the live preview to inspect the generated JSON payload and the matching cURL command before you submit the sandbox request.
- 7
Send the Request and Verify the Result
Click Send Request to post the sandbox request through the documentation proxy. The response panel shows the latest HTTP status and response body returned by the sandbox API.
Then check the Recent Transactions section to confirm that the transaction was recorded for the API key you entered and to review its latest status.
Before using Sandbox Env, make sure you have already created a sandbox API key from the merchant portal. If not, log in at https://merchant.prod.afropays.co/auth/login and create the key after switching the dashboard into sandbox mode.
Every payment simulation must use a unique merchant order id. You can enter one manually or switch the Sandbox Env field into auto-generated mode so the page prepares the next value for you.
Your callback URL must be reachable. Use a public hosted callback endpoint, follow Expose Endpoint to test with a local route, or follow Callback Testing to use a mock API receiver.