Payment gateway sandbox testing: a checklist before you go live

Payment gateway sandbox testing is how you find out that your checkout, notifications, invoices and emails work before a real customer finds out for you. A sandbox (or test mode) is a copy of the gateway's system that accepts test credentials and test card numbers and behaves like the real thing, without moving real money. Every South African gateway worth using offers one, and an hour spent there saves days of untangling live payments later.

This checklist covers what to test, how to keep test and live apart, and how to switch over safely.

What a sandbox is, and isn't

A sandbox lets you:

• Create payments with test credentials and the gateway's published test cards or test accounts.
• Simulate successful, failed and cancelled payments.
• Receive real notifications (webhooks) from the gateway's test environment.

It doesn't fully reproduce:

• Every bank's 3-D Secure screens and real-world declines.
• Real settlement timing, fees and payouts.
• The exact behaviour of every payment method; some methods aren't available in test mode at all.

So sandbox testing proves your integration and your process. A small live test afterwards proves the real-world path.

Before you start

1. Get sandbox credentials from each gateway you'll use. They are different from live credentials.
2. Use the gateway's published test cards and accounts. Never test with a real card number or real customer data in a sandbox.
3. Set up a test customer with an email address you control, so you can see every email they would receive.
4. Point notifications at the right place. Many gateways need a notification (webhook) URL configured; check whether the sandbox needs its own.
5. Write down what "correct" looks like for each scenario: the payment status, the invoice status, the emails, the webhook your system receives.

Scenarios to test

Core payment outcomes

• Successful payment for a once-off amount
• Declined payment (using the gateway's decline test card or method)
• Customer cancels on the gateway's page
• Customer abandons the page without cancelling
• Customer pays, then closes the browser before returning to your site

For each, check the payment status, what the customer sees, and what your system received.

Notifications and webhooks

• The gateway's notification arrives and is verified
• Your own webhook endpoint receives the event and verifies its signature. See webhook signature verification
• A repeated notification doesn't fulfil the order twice
• Your system copes if your endpoint is briefly unavailable and the event is retried

Invoices, receipts and emails

• Paying an invoice marks it paid, with the correct amount and VAT
• Partial payment leaves the right balance
• The receipt email arrives, with the PDF attached and your branding
• Emails land in the inbox, not spam. See invoice emails going to spam

Refunds

• A full refund and a partial refund are recorded against the right payment
• The customer's documents and your accounting reflect the refund

Recurring payments, if you use them

• A subscription starts and the first payment completes
• A renewal is recorded against the subscription
• A failed renewal triggers your retry and reminder process. See dunning management
• For debit orders: a mandate can be signed and a test collection run on a sandbox account

Mobile and edge cases

• The full flow works on a phone, including payment links opened from WhatsApp or email
• Mobile money prompts (if offered) can be approved and declined
• Amounts with cents, and the smallest and largest amounts you expect, are handled correctly

Keep test and live strictly apart

The most expensive testing mistakes happen after go-live, when test and live get mixed:

• Separate credentials. Store sandbox and live keys separately and label them clearly.
• Separate notification URLs where the gateway allows it, so a test notification can never update a live payment.
• Flag test payments. Your systems should know whether a payment came from a sandbox, and refuse to settle a real invoice with a test payment.
• Never test on live. If you must check the live path, use a small real payment with your own card and refund it.

Go-live checklist

1. Complete any business verification your provider requires. Gateways and payment platforms must know who they are collecting money for.
2. Replace sandbox credentials with live credentials and switch off test mode.
3. Confirm the live notification URL in the gateway's portal, where it needs to be configured.
4. Make one small live payment with your own card, check every step, then refund it.
5. Remove or clearly mark test customers and data.
6. Tell your team what has changed and who to call if something looks wrong.

The first week live

• Check every payment status daily against the gateway's portal.
• Watch your notification and webhook logs for failures or rejected notifications.
• Reconcile the first settlements to your bank statement. See payment gateway settlement reconciliation.
• Read customer queries carefully; they find the edge cases you didn't.

For the wider build process, see our payment API integration guide.

How CentraPoint helps

Every gateway you connect in CentraPoint has a Sandbox (test mode) switch. Leave it on while you test with the gateway's test credentials, use Test to check the credentials where the gateway supports a connection test, make a test payment, check the webhook log, then switch sandbox off and enter your live credentials. Sandbox and live configurations of the same gateway get different notification URLs, so they can't be confused.

New CentraPoint accounts can use sandbox gateways straight away for payment links, invoices, hosted checkout, subscriptions and EFT orders. Live payments unlock once your business has been verified, as FICA and the card schemes require. Payments and webhooks carry a sandbox flag, so your systems can refuse to settle a real invoice with a test payment. Developers can import the Postman collection from the docs to try every API call. See the get started guide and the business verification guide.

Frequently asked questions

What is a payment gateway sandbox?

It's a test environment provided by the gateway that behaves like the live system but uses test credentials and test card numbers, so no real money moves.

Can I use my own card in sandbox mode?

No. Sandboxes expect the gateway's published test cards and accounts. To test the live path, make a small real payment after go-live and refund it.

Why do my sandbox payments not show up in my live account?

Sandbox and live are separate environments with separate credentials and data. That separation is deliberate, so test payments never mix with real ones.

How long should payment testing take?

It depends on how many gateways, payment methods and flows you use. Work through every scenario in the checklist for each gateway, and don't go live until each one behaves as you expect.