Sandbox environment

Sandbox is Payscribe’s safe integration environment. Use it to make authenticated requests, build complete product flows, and validate webhooks without processing real customer money.

Use sandbox until your full workflow is provenEvery developer should be able to create a test request, receive the expected event, and reconcile its result before requesting production access.

The environment boundary

Sandbox is a separate environment, not simply a different key. Keep its credentials, endpoints, webhook configuration, and test data isolated from production.

Development configurationPAYSCRIBE_API_KEY=ps_pk_test_...PAYSCRIBE_BASE_URL=https://sandbox.payscribe.ng/api/v1

1 · Your test serverApplication codeReads test configuration from its environment.

→

2 · Payscribe sandboxTest API and eventsUses sandbox data and never processes real money.

→

3 · Sandbox webhookYour HTTPS test endpointVerifies events before updating test state.

Do not cross the boundary: a ps_pk_live_... key, production base URL, or production webhook endpoint does not belong in a sandbox build.

Sandbox settings

Setting	Sandbox value	Production value
Base URL	https://sandbox.payscribe.ng/api/v1	https://api.payscribe.ng/api/v1
API key	ps_pk_test_...	ps_pk_live_...
Webhook secret	ps_test_...	ps_live_...
Purpose	Build and validate integration behaviour	Approved real-money operations

Configure your development server

Store the sandbox key and base URL in your server environment. Do not add a key to browser code or commit it to source control.

macOS / Linux

export PAYSCRIBE_API_KEY="ps_pk_test_your_api_key"
export PAYSCRIBE_BASE_URL="https://sandbox.payscribe.ng/api/v1"

PowerShell

$env:PAYSCRIBE_API_KEY = "ps_pk_test_your_api_key"
$env:PAYSCRIBE_BASE_URL = "https://sandbox.payscribe.ng/api/v1"

Use the Quickstart to make a safe first request and confirm that the sandbox connection works.

Simulate an inbound payment

The virtual-account simulator creates a sandbox inbound transfer so you can test the flow that matters in production: incoming payment, webhook delivery, deduplication, and reconciliation.

The simulator request includes a hash built from your sandbox test secret key (ps_sk_test_..., not the ps_pk_test_... key in the Authorization header) and the request fields:

hash = uppercase(SHA512(test_secret_key + sender_account_number + account + bank + amount + ref))

Use a new ref for every distinct test, then follow the Simulate transfer API reference for the request body and working examples.

The two-step sandbox flow delivers the webhook:

1. simulate-transfer creates the transaction and credits the business collection wallet, but returns Payment Confirmed! without dispatching a webhook.
2. confirm-payment (pass the returned session_id and account_number) looks the transaction up and dispatches accounts.payment.status to your configured test webhook URL — this is how sandbox exercises your webhook handler. See confirm payment.

Test the webhook, not only the API response

The simulator response means Payscribe accepted the test request. Your integration is not complete until your webhook handler verifies and records the corresponding accounts.payment.status event from confirm-payment.

What sandbox does and does not prove

Sandbox can prove	Sandbox cannot prove
Authentication, request validation, response handling, webhook verification, duplicate handling, and reconciliation logic	Real-bank availability, settlement timing, production approvals, live risk decisions, or your production infrastructure

When your complete sandbox flow works, use Sandbox testing to run the release test matrix. Do not switch credentials manually as a final step; complete the go-live checklist first.