Sandbox testing

Sandbox is where you prove that your integration works as a system—not merely that one endpoint returns 200. Test your API requests, webhook handling, reconciliation, and failure recovery before you use production credentials.

What sandbox provesYour application can make authenticated test requests, process the resulting events safely, and recover from common failures without moving real money.

Keep environments separate

Environment	Base URL	Key prefix	Intended use
Sandbox	https://sandbox.payscribe.ng/api/v1	ps_pk_test_...	Development, automated testing, and integration validation
Production	https://api.payscribe.ng/api/v1	ps_pk_live_...	Approved real-money operations

Keep credentials, webhook endpoints, customer data, and logs separate between environments. A production key must never appear in a test build or repository.

Test one complete collection flow

For collections, the virtual-account simulator lets you create a sandbox inbound-payment event. This is the most useful first end-to-end test because it verifies both your API integration and your webhook processing.

1 · PrepareYour test applicationCreate a customer and virtual account.

→

2 · TriggerPayscribe sandboxSimulate an inbound transfer with a unique ref.

→

3 · VerifyYour HTTPS webhookVerify raw body + signature; store event ID once.

→

4 · ReconcileYour business stateMatch the event to the wallet or transaction record.

Run the flow

1. Create a sandbox customer and virtual account using the Virtual accounts guide.
2. Register a sandbox webhook endpoint that is publicly reachable over HTTPS.
3. Implement signature verification from the Webhooks guide, using the raw request body.
4. Call Simulate transfer with a new reference such as test_collection_001.
5. Return 200 promptly from your webhook handler, then process the event asynchronously.
6. Retrieve the resulting transaction or wallet state and reconcile it with the event.

Record correlation values

For every test, record the request ref, HTTP status, X-Payscribe-Event-Id, and final transaction or ledger result. These values make a failed test diagnosable.

Test the failure paths that cause real incidents

Run this matrix before a release. The expected result is your application behaviour—not simply the API response.

Scenario	How to create it	Your application must do
Successful collection	Simulate a valid inbound transfer.	Verify the webhook, reconcile the event, and update business state once.
Duplicate client submission	Repeat a write request with the same ref.	Do not create another order or payout; find and reconcile the original operation.
Timeout after submission	Interrupt the client after sending a write request.	Keep the same ref; check the operation state before taking another action.
Invalid credentials	Use a deliberately invalid test key.	Surface a safe authentication failure; never log or display the key.
Invalid input	Omit a required field or use an invalid bank/account value.	Map the validation error to an actionable correction; do not retry unchanged input.
Invalid webhook signature	Change one byte of a saved payload or signature.	Reject the event and leave business state unchanged.
Duplicate webhook delivery	Deliver the same event ID twice to your handler.	Process the event once only.
Slow webhook handler	Delay processing beyond your quick acknowledgement path.	Queue the work and return 200 quickly.
Rate limit response	Send controlled POST requests until the service returns 429.	Back off with jitter; do not retry in parallel.

Expose a local webhook safely

During local development, a webhook endpoint must be reachable from Payscribe over HTTPS. Use a secure tunnel approved by your team to expose a temporary local URL, then register that URL in the sandbox dashboard.

Use only for local testingTemporary tunnel URLs are useful for sandbox debugging, not production traffic.

Keep the raw bodyVerify the signature before parsing or transforming the webhook payload.

Separate processingAcknowledge fast, then queue reconciliation and fulfilment work.

What to automate

Add the successful collection, duplicate-reference, invalid-signature, and 429 scenarios to CI or a pre-release test suite. Use unique references, for example ci_20260815_001; never reuse a previously successful reference as a new operation.

Sandbox sign-off

Before moving to production, confirm that you can:

• Make a sandbox request with a server-side test key.
• Handle a successful API response and verified webhook.
• Safely reject an invalid webhook signature.
• Process a duplicated event ID once.
• Recover a timed-out write using the original reference.
• Explain a failed test using your logs and recorded correlation values.

Sandbox validates integration behaviour. It does not validate real-bank availability, settlement timing, production risk decisions, or your own production infrastructure. When you are ready, complete the go-live checklist.