Skip to main content

Sandbox vs Production

NextAPI provides a sandbox environment for development and testing. The sandbox behaves like production but no real money moves.

Environments​

SandboxProduction
Base URLhttps://api.partners.nextpay.world/v2/https://api.partners.nextpay.world/v2/
CredentialsSandbox Client ID + SecretProduction Client ID + Secret
Real moneyNoYes
WebhooksSimulatedReal provider events
Payout completionSimulated responseActual bank/e-wallet transfer
Rate limitsSame as productionSame as production

The base URL is identical — the environment is determined by which credentials you use. Sandbox credentials only authorize operations in the sandbox; production credentials authorize live financial transactions.

Getting sandbox credentials​

Request sandbox access via the Sandbox page. You will receive:

  • Sandbox Client ID
  • Sandbox Client Secret
  • A pre-funded test account you can use immediately

Test scenarios​

Payout simulation​

In the sandbox, payouts transition through states automatically based on the amount you submit:

Amount (centavos)Simulated outcome
Any standard amountcompleted — normal success
Ending in 01 (e.g., 1000001)failed — insufficient funds simulation
Ending in 02 (e.g., 1000002)failed — invalid account simulation
Ending in 03 (e.g., 1000003)failed — bank unavailable simulation

Use these trigger amounts to test your error handling paths without needing to set up edge-case conditions manually.

Payment collection simulation​

Payment Intents and Funding Methods in the sandbox do not receive real payments. To simulate an incoming payment:

  1. Create a Funding Method or Payment Intent
  2. Use the sandbox simulation endpoint (contact NextPay for access)
  3. A webhook event is dispatched as if a real payment occurred

Webhook simulation​

Configure your webhook endpoint in the sandbox the same way as production. Sandbox webhooks are delivered immediately after state changes, without the delays that real provider confirmations introduce in production.

Sandbox limitations​

  • No real bank connections — recipient validation uses simplified rules
  • No PESONet batch windows — PESONet payouts complete immediately in sandbox
  • No InstaPay network checks — BANK_UNAVAILABLE only appears via trigger amounts
  • Pre-funded accounts — your sandbox account has a fixed starting balance; contact support if you need it reset

Production go-live checklist​

Before switching to production credentials, verify each item:

  • Authentication tested — all requests use Basic Auth with the correct header format
  • Idempotency keys — every payout request includes a unique X-Idempotency-Key
  • Webhook endpoint deployed — your production URL is publicly accessible via HTTPS
  • Webhook signature verification — you verify x-nextpay-signature on every incoming event
  • Error handling — you handle INSUFFICIENT_FUNDS, BANK_UNAVAILABLE, and 500 errors with retry logic
  • Centavos amounts — all amounts are in PHP minor units (PHP 100.00 = 10000)
  • External IDs — you set external_id on resources to link them to your internal records
  • Credential storage — production Client Secret is stored in environment variables, not source code
  • Logging — you log API responses including error codes for debugging and reconciliation
  • Reconciliation — you have a process to verify payouts against your internal records

Switching environments​

To switch from sandbox to production, replace your credentials in your environment variables:

# Sandbox
NEXTAPI_CLIENT_ID=sandbox_YOUR_CLIENT_ID
NEXTAPI_CLIENT_SECRET=sandbox_YOUR_CLIENT_SECRET

# Production
NEXTAPI_CLIENT_ID=YOUR_PRODUCTION_CLIENT_ID
NEXTAPI_CLIENT_SECRET=YOUR_PRODUCTION_CLIENT_SECRET

No code changes are needed — the base URL is the same.