What we do
Tools
Industries
Department
How we workLet's talk →
Home/GoCardless/GoCardless API Before Your First Live Payment
GoCardless

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.

The basics

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. 1

    Collect through a Billing Request

    Create a Billing Request with a mandate_request for direct debit, a payment_request for 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. 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. 3

    Send an idempotency key with every create

    An Idempotency-Key header of up to 128 characters lets one key succeed once. Send the same request again and you get a 409 idempotent_creation_conflict, with the existing resource's ID in links.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. 4

    Register the webhook endpoint and verify every delivery

    Developers Webhooks

    GoCardless signs each delivery with an HMAC SHA256 hex digest of the raw body, keyed with the endpoint secret, and sends it in the Webhook-Signature header. 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. 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 Origin headers, 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.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.