Sandbox

Test your integration without moving real money.

How the sandbox works

The sandbox is a path, not a separate host. There is no separate sandbox domain. Test traffic uses the same base URL as live — https://api.quatapay.com/api/v1 — but hits the /gateway/sandbox/ path with a test key:

POST https://api.quatapay.com/api/v1/gateway/sandbox/payments

The sandbox path mirrors the live /gateway/payments API exactly — same request and response shape. Only the path and the key prefix differ.

Sandbox API keys

Use keys with the qpay_test_ prefix. All operations in test mode operate on isolated sandbox wallets with no real XAF. The live /gateway/payments endpoint rejects a test key with 403, and the sandbox path rejects a live key the same way.

Generate test keys from your merchant dashboard under Developer → API Keys — ensure the mode selector shows Test.

Pre-funded sandbox wallets

When you register and log in with a sandbox test user account, the account is automatically credited with 100,000 XAF in sandbox balance so you can immediately test checkout flows.

To reset your sandbox balance, go to Developer → Sandbox in the merchant dashboard and click Reset sandbox wallets.

Simulating scenarios

Send specific customer_reference values to trigger deterministic outcomes:

Test checkout flow

1. Create a test payment intent by POSTing to https://api.quatapay.com/api/v1/gateway/sandbox/payments with your qpay_test_ key
2. Open the returned data.checkout_url in your browser
3. Log in with a sandbox user account (or create one — pick any email, no SMS is sent in test mode)
4. Confirm the payment
5. Watch the webhook arrive at your endpoint

Completing a test payment programmatically

Test mode has no real app to approve a payment. To finalize a test payment from your integration tests, call the simulate endpoint with the payment's slug and your test key:

POST https://api.quatapay.com/api/v1/gateway/sandbox/payments/{slug}/simulate
Authorization: Bearer qpay_test_YOUR_KEY
Content-Type: application/json

{ "outcome": "succeeded" }

To simulate a failure, send { "outcome": "failed", "failure_reason": "INSUFFICIENT_FUNDS" }.

This fires the same gateway.payment.* webhooks as a real completion, with "simulated": true added to the payload.

Webhook testing

In Developer → Sandbox, you can click Trigger test event to send a synthetic gateway.payment.succeeded or gateway.payment.failed webhook to your configured endpoint — useful for testing your handler without going through the full checkout flow.

Differences from production

Going live

When you're ready to accept real payments:

1. Complete merchant KYC in the dashboard
2. Generate a qpay_live_ API key
3. Swap your key and update your webhook endpoint URL to use the live secret
4. Remove any sim_* customer references from your integration