Testing & Sandbox

Test mode routes every request through a sandbox that behaves identically to production — same API, same webhooks, same dashboards — but no real money moves and no real bank, wallet, or card is involved.

Do I need a real bank or GCash account to test?

No. Never use a real bank or wallet for testing — it's not required, and test-mode payments don't actually reach any real payment provider. Everything is simulated server-side.

The only time real banks come into play is once you're on sk_live_* keys in production, after KYB approval + activation. In test mode, all you need is your sk_test_* key.

Three ways to drive test payments

Pick whichever fits your workflow. All three use sk_test_ keys; all three fire real webhooks.

1. Dev Controls on the sandbox checkout page (easiest)

Every test payment's checkout_url opens the NexusPay sandbox page. In the top-right of that page there's a Dev controls toggle. Expand it and you get three buttons:

• ✓ Success — transitions the payment to succeeded, credits the test ledger, fires payment.succeeded webhook.
• ✕ Fail — transitions to failed, fires payment.failed.
• ◷ Expire — transitions to expired, fires payment.expired.

Best for ad-hoc testing during development. You can flip through all outcomes in seconds.

2. Deterministic amounts (great for automated tests)

The cents portion of the amount drives the outcome automatically in the sandbox:

Best for unit / integration tests — you can deterministically test success, failure, and expiry paths without any UI interaction.

curl -X POST https://nexuspayph.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 100.01, "currency": "PHP", "method": "gcash_qr" }'

3. MagiaWallet demo (for end-to-end pitches)

MagiaWallet is a simulated ewallet (phone-framed purple UI, ₱12,450.75 starting balance, fake recent transactions). In demos:

1. Create a test payment as usual. You get a pay_xxx id and a checkout_url.
2. Open /demo-wallet in another tab.
3. Tap Scan QR, paste the payment id or full checkout URL.
4. Review the branded confirmation card (merchant name, amount, before/after balance).
5. Tap Pay → enter demo PIN 1234 → green checkmark animation.
6. Webhook fires on your merchant backend. Balance deducts in the wallet. Full loop in ~10 seconds.

Best for live client demos — it makes the complete flow visible: merchant creates payment → customer scans + confirms → merchant gets webhook.

Test cards for the card method

The sandbox card form is pre-filled with a test card. Any expiry / CVC values work.

Real card numbers can't be charged in test mode — they'd be treated the same as the test card. No PCI risk in sandbox.

Test keys never move money

• All test ledger entries are tagged environment=test. Your live balance is physically isolated — the database enforces the split.
• You can generate unlimited test transactions. No rate limits on the test ledger itself (standard per-key API rate limits still apply — 120 req/min).
• Test and live webhooks go to separate endpoints. Register one endpoint per environment in the dashboard to avoid cross-contamination.
• Test-mode payments use the NexusPay sandbox as their provider, never DirectPay or PayGram. So no provider-side fees, no real wallet authorisations, no partial chargebacks.

How do I flip from test to live?

In order:

1. Complete KYB + activation from the merchant dashboard.
2. Receive your sk_live_* keys (shown once on activation).
3. Register a separate webhook endpoint for environment: live from your dashboard.
4. Swap the API key your server uses. Everything else in your integration stays identical.

Because the API and webhook shapes are identical, there's no code change between test and live beyond the API key. Your sandbox-passing integration will work in production.

FAQ

Summary