GoCardless API: What to Get Right Before the First Live Mandate
The GoCardless API runs on two hosts, sandbox and live, each with its own access tokens. Every request carries a bearer token and a GoCardless-Version header. Customers authorize mandates and payments on a hosted page that a Billing Request starts, and webhooks report what happened next. The edges are where a first build slips: a retried request that creates a second payment, or a handler that assumes each event arrives once and in order.
Hosts: https://api-sandbox.gocardless.com/ for testing, https://api.gocardless.com/ for live. A sandbox token only works on sandbox, and a live token only on live.
Auth: Authorization: Bearer <token>, with the token created in the dashboard's Developers area. Pick read-only for reporting and read-write for anything that creates customers, mandates or payments. The token is shown once.
Version: every request needs GoCardless-Version: 2015-07-06, the current release.
Format: JSON in and out. A POST or PUT without the right Content-Type fails with invalid_content_type.
Too many requests: a 429 with rate_limit_exceeded is safe to retry. The ratelimit-remaining and ratelimit-reset headers show where you stand in the current window.
Sandbox account to a GoCardless collection you can rely on
- 1
Collect through a Billing Request
Create a Billing Request with a
mandate_requestfor direct debit, apayment_requestfor a one-off payment, or both for an instant first payment plus a mandate. Then create a Billing Request Flow and send the customer to the hosted URL it returns.Watch for: older guides built on Redirect Flows. GoCardless has deprecated them, and new integrations can't use them.
- 2
Trust the webhook, not the redirect
The customer comes back to your site when they've finished, but GoCardless's advice is to confirm the outcome from webhooks. Read the mandate and payment IDs off the fulfilled Billing Request.
- 3
Send an idempotency key with every create
An
Idempotency-Keyheader of up to 128 characters lets one key succeed once. Send the same request again and you get a409 idempotent_creation_conflict, with the existing resource's ID inlinks.conflicting_resource_id. Keys are honored for at least 30 days.Watch for: keys generated fresh on each retry. Derive the key from your own invoice or schedule ID, so a retry reuses it.
- 4
Register the webhook endpoint and verify every delivery
Developers › WebhooksGoCardless signs each delivery with an HMAC SHA256 hex digest of the raw body, keyed with the endpoint secret, and sends it in the
Webhook-Signatureheader. Return 498 when it doesn't match, and a 2xx within 10 seconds when it does.Watch for: frameworks that parse the JSON before you hash it. The digest is of the raw body, byte for byte.
- 5
Expect batches, repeats and the wrong order
One delivery can hold several events, the same event can turn up in more than one delivery, and deliveries can arrive out of order. Store the event IDs you've handled, and fetch the resource's current state from the API before acting. A failed delivery gets up to 8 more attempts, spaced further apart each time.
Before the GoCardless integration takes live money
Which jobs really need a read-write token?
Reporting and reconciliation only read. Give them their own read-only token, so the job that creates payments holds the only token that can.
What does your app do when a mandate is canceled or fails?
The next collection can't run. Decide whether the plan pauses, the customer gets a fresh authorization link, or someone phones them, before the first one happens for real.
Does a chargeback reach a person?
A payment that was confirmed and paid out can still be charged back by the customer's bank. If nothing reads that event, the invoice stays marked paid.
Will your network let the webhooks in?
If inbound traffic is filtered by source, GoCardless publishes the addresses its webhooks come from. Sandbox and live deliveries carry different
Originheaders, which helps when both point at one service.
Reading a GoCardless payout back to the invoices inside it
A payout reaches the bank as one amount covering many customers' payments, less GoCardless's fees, and sometimes less a refund or chargeback from an earlier collection. The payouts API, and the items listed under each payout, say which payments and deductions make up that number.
n-frames builds the job that reads each payout as it's paid, matches every payment to its invoice in your accounting system or CRM, books the fees, and flags only the lines that don't match. It runs on the same verified webhook receiver: confirmed payments mark invoices paid, and failures and chargebacks reopen them.
GoCardless API questions before go-live
Does GoCardless have a sandbox for testing?
Yes. The sandbox has its own dashboard, its own access tokens and its own API host, api-sandbox.gocardless.com. You can create customers, mandates and payments there without a real bank account involved, then switch the token and host for live.
What is GoCardless's open banking payment option?
Instant Bank Pay: a one-off payment over open banking, in GBP through Faster Payments and in EUR through SEPA Instant. There's no mandate, so the customer authorizes each payment in their own bank. Put a payment_request and a mandate_request in one Billing Request and the first payment goes through instantly while the mandate is set up from the same bank details. GoCardless's JavaScript Drop-in doesn't support Instant Bank Pay, so use the hosted pages for it.
Does GoCardless integrate with Salesforce?
Partner apps have offered GoCardless connections for Salesforce, so check GoCardless's partner listings for the current ones. When payment and mandate status has to land on your own objects, invoices or renewal fields, it's a build on the API and webhooks, and that's work n-frames does.
What do GoCardless webhooks actually tell you?
That something changed, in a batch of one or more events. Each event names a resource type and an action: a payment confirmed, failed or charged back, a mandate created, canceled or failed, a payout paid. Treat it as a prompt, fetch the current state from the API, and act on that.
Who builds what happens after a GoCardless webhook arrives?
That layer is what n-frames writes: the verified, idempotent receiver, the update to your billing or CRM record for each payment and mandate event, and the payout reconciliation that ties every collection to its invoice.