Testing and Sandbox#
The sandbox is a separate GoCardless environment where you can build and test your integration without moving real money. You can create customers, mandates, and payments, then trigger failures and chargebacks on demand.
How the sandbox works#
The sandbox and live environments are completely separate. Each has its own account, dashboard, access tokens, and data. Nothing you create in the sandbox carries over to live.
Payments and mandates move through their lifecycle at the same speed as in live. For example, a Bacs mandate takes 3 working days to activate. Use the scenario simulators to move a resource to the state you need straight away.
| Service | Sandbox | Live |
|---|---|---|
| API | https://api-sandbox.gocardless.com/ | https://api.gocardless.com/ |
| Dashboard | https://manage-sandbox.gocardless.com | https://manage.gocardless.com |
| Hosted payment pages | https://pay-sandbox.gocardless.com | https://pay.gocardless.com |
| OAuth (Connect) | https://connect-sandbox.gocardless.com | https://connect.gocardless.com |
| Health check | https://api-sandbox.gocardless.com/health_check | https://api.gocardless.com/health_check |
The GoCardless MCP also works with your sandbox account. Choose Sandbox when you connect.
Get started#
- Create a sandbox account.
- In the sandbox dashboard, go to the Developers page, select Create, then Access token. Copy the token straight away, because you can only view it once.
- Make your first request against the sandbox API.
The Set up guide walks through these steps and how to configure a client library. To see a working request, follow Send your first API request.
What you can test#
| I want to test | Use |
|---|---|
| A payment failing or being charged back | Scenario Simulators |
| A customer completing a payment or mandate with a bank account | Test Bank Details |
| Bank authorisation with BankID | BankID Scenario Simulators |
| My webhook handler | Testing Webhooks (Dashboard) |
| My webhook handler on my local machine | Testing Webhooks (CLI) |
| Requests to the API without writing code | Postman Collection |
| Bank Account Data | Testing Bank Account Data |
| A partner integration, including OAuth | Testing your integration |
Differences from live#
The sandbox behaves like live in most ways, but these differences can catch you out.
Customer emails are restricted#
The sandbox only sends customer notification emails to addresses that belong to a user on your organisation, or that use a disposable email domain. You can also use sub-addresses of a user's email. For example, if you@example.com is a user on your organisation, emails to you+test@example.com are sent. Emails to any other address are not sent.
Webhooks identify their environment#
Each webhook includes an Origin header with the environment that sent it: https://api-sandbox.gocardless.com for the sandbox and https://api.gocardless.com for live. Use it to tell sandbox and live webhooks apart. See Webhooks.
Some endpoints are restricted in live#
Some endpoints are restricted in live unless your account has been approved. Check the Restrictions page before you rely on an endpoint that works in the sandbox. Creating payments with Billing Requests works the same way in both environments.
Before you go live#
Make sure your integration handles the paths that go wrong as well as the happy path. Use the scenario simulators to test each of these:
| Scenario | How to test it |
|---|---|
| Payment succeeds and is paid out | payment_paid_out, or billing_request_fulfilled_and_payment_paid_out from checkout |
| Payment fails | payment_failed |
| Payment fails later than usual | payment_late_failure (not Autogiro) |
| Payment is charged back | payment_charged_back |
| Mandate fails | mandate_failed (not SEPA, since SEPA mandates are submitted with the first payment) |
| Mandate expires | mandate_expired (not Autogiro, BECS NZ or PAD) |
| Customer switches bank account | mandate_transferred (Bacs only) |
| Webhook is delivered more than once | There is no simulator. Resend a webhook with Testing Webhooks (Dashboard) or the CLI |
When you're ready, follow the Go-live checklist.