API integration for GoCardless
We build your GoCardless connector
We build the GoCardless connector to the GoCardless API to sign SEPA mandates, collect on a real interbank calendar and track failures, chargebacks and payouts.
- Senior product team
- payment integrations in production
- from scoping to monitoring
What does the GoCardless API do and why collect payments by bank transfer?
GoCardless is a SEPA and ACH direct debit operator used for recurring payments: subscriptions, monthly invoices, instalment plan settlements. Its API lets your application create a direct debit mandate online, schedule payment dates, and be notified of each successful payment or failure. You integrate it when a card payment is not the right method: large amounts, B2B clients, long-term subscriptions, and you want to collect payment without the client having to renew a card or enter details each time.
What our clients build on the GoCardless API
B2B subscription on SEPA Direct Debit
Mandate signed on a hosted flow, schedule set 1 interbank business day before due date, no card to chase.
Payment in instalments
Training, works, equipment: each due date is a tracked payment, with chasing wired to details.cause, not a bank code.
Dues and memberships
Annual call, automatic advance notice, revoked mandates handled. The signed PDF and the IBAN spreadsheet disappear.
Paying introducers
Outbound payments created then approved at two levels in the back office. A business reference blocks a double transfer.
What it changes in collections
Engineering in service of a measurable outcome: fewer card failures, a living mandate, readable cash.
No more expiring cards
SEPA Direct Debit holds as long as the mandate holds. Failure rate becomes a balance problem, not a card lifecycle problem.
A schedule the bank can honour
Submit 1 interbank business day before due date, notify 2 working days before. You stop promising an immediate debit.
Failure has a readable cause
details.cause is normalised, unlike the bank code. The reminder states the real reason, not a technical label.
Cash, not invoices issued
confirmed, paid_out, failed, charged_back: the dashboard shows what was collected, not what was billed.
How we ship your GoCardless connector
Scoping
Billing Requests or approved pages, SEPA scheme, interbank calendar, outbound payments. We settle the live constraint first.
Development
Typed connector, GoCardless-Version on every call, business Idempotency-Key, HMAC webhook with a 498 response.
Acceptance testing
Mandate, failure, 409 treated as success, out-of-order event, invalid IBAN blocked before creation.
Monitoring
Alerts on unprocessed events, a mandate log, a health dashboard. You know a flow is broken before your customers do.
What the GoCardless API allows
- Billing Requests and hosted flow
- Cycle pending, ready_to_fulfil, fulfilled, cancelled. GoCardless recommends Billing Request Flows for conversion and compliance.
- SEPA collections and subscriptions
- Payments, subscriptions backed by a mandate. Billing Request subscription_request does not cover SEPA (ACH and PAD only).
- IBAN check
- bank_details_lookups checks modulus and reachability before creating a mandate. A bad IBAN costs a full bank cycle.
- Outbound payments
- Create then approve. Outbound POSTs share 300 requests per minute, about 150 payments (create then approve).
The vocabulary of the GoCardless API
- GoCardless-Version
- Required header, one published version: 2015-07-06. Without it, missing_version_header. Additions arrive without changing the date.
- Idempotency-Key
- Up to 128 characters, honoured for at least 30 days. A conflict returns 409 idempotent_creation_conflict with links.conflicting_resource_id: that is a success.
- details.cause
- Normalised key, independent of the bank scheme. details.reason_code changes from bank to bank: a state machine wired to it breaks when you change country.
- meta.webhook_id
- Identifies the delivery attempt, not the event. Deduplication is on event.id. Deduping here only shows up in an incident.
- 498 Token Invalid
- Expected response if the signature is invalid: GoCardless logs it and does not retry. A 200 would look like a successful delivery.
- Billing Request
- The modern object (pending, ready_to_fulfil, fulfilled, cancelled). In live mode without approved pages, it is the only legal path to create a mandate.
The real constraints of the GoCardless API
At-least-once, never in order
payment.confirmed can arrive before payment.created. GoCardless does not guarantee exactly-once. Re-read the resource via the API on every webhook, infer nothing from the sequence.
Live mode is not the sandbox
Without your pages approved by the sponsor bank, creating a customer, bank account and mandate is forbidden outside Billing Requests. A sandbox prototype can be illegal as-is.
Three rate limits, not one
1,000 requests per minute as standard, 60 on GET /balances, 300 POSTs shared across outbound payments (about 150 payments). 429 is too late: we read ratelimit-*.
A 409 conflict is good news
idempotent_creation_conflict points at the resource already created. Treating it as an error retriggers a second collection or blocks the queue. SDKs that generate the key for you are a trap.
Billing Requests or direct endpoints?
Two ways to create a mandate. In live mode, the choice is often not a choice.
| Criterion | Billing RequestsHosted flow | Direct endpointsCustomer, account, mandate |
|---|---|---|
| Live without approved pages | Allowed | Forbidden |
| Bank Authorisations | Only via hosted interfaces | Not creatable outside GoCardless flows |
| Conversion and compliance | Flow optimised by GoCardless | Must be approved by the sponsor bank |
| SEPA subscription | Classic Subscription object afterwards | Same, once the mandate exists |
| Sandbox | Available | Available, misleading for live |
| JavaScript flow | Outside this path | Restricted in live mode |
| The right case | Almost every French project | Pages already approved, whitelabel partner |
We raise this restriction in the first meeting. A prototype built on the direct endpoints is often thrown away before go-live.
What we measure on a GoCardless integration
The other payment APIs
If SEPA Direct Debit is not the right fit, these options are worth discussing during scoping.
GoCardlessWe build your GoCardless connectorThis page
StripeCards and Billing, when the buyer has no IBAN or a card lifecycle suits you.
PayPalAn account the buyer already has, rather than a Direct Debit mandate.
SumUpIn-person collection, when the sale closes on a terminal.
MollieWe build your Mollie connectorWe combine GoCardless with
The stack that surrounds GoCardless on our projects.
GoCardless integration: your questions
Three steps. First a Bearer token and the GoCardless-Version: 2015-07-06 header on every request. Then a Billing Request plus hosted flow for the mandate, then payments or subscriptions, with an Idempotency-Key derived from the invoice, not the one generated by the SDK. Finally webhooks: HMAC-SHA256 on the raw body, 498 if the signature is invalid, 204 on an unknown type, dedupe on event.id, re-read the resource because events arrive neither once nor in order. The sensitive part is not the call, it is the live constraint and the SEPA calendar.
It depends on the mandate flow and collections. A B2B subscription with a hosted flow and a SEPA schedule is shorter than a tool with outbound payments, cause-based chasing and a cash dashboard. A first useful flow ships in two to three weeks. A full chain is closer to six to eight weeks. The live restriction (Billing Requests without approved pages) is settled at scoping, not in acceptance testing. We give a firm estimate before we start.
Billing Requests plus Billing Request Flows are the hosted path, required in live mode for as long as your payment pages have not been approved by the sponsor bank. Customer, bank account and mandate creation endpoints, and the whole JavaScript flow, are then forbidden. The sandbox exposes all of them, which misleads. Bank Authorisations can only be created from hosted interfaces. For a standard French project, we start from Billing Requests. Direct endpoints are only discussed if your pages are already compliant.
Verify Webhook-Signature as hexadecimal HMAC-SHA256 on the raw body, return 2xx after persisting, 498 on an invalid signature. Dedupe on event.id, never on meta.webhook_id (that is the attempt). Re-read the payment via the API, because a confirmed can precede the created. A business Idempotency-Key (collection:{invoice}:{due}) plus treating 409 as success avoid a second collection after a timeout. The handler stays under 10 seconds: verify, enqueue, respond. Business work happens in the background.
Yes. We push each confirmed or paid_out payment with the invoice reference into Pennylane or your tool, and failures (failed, charged_back) feed chasing. A periodic consistency check flags the gap between collections and entries, with no silent fix. The SEPA calendar (submit 1 interbank business day before, notify 2 working days before) is reflected in the schedule you show: we do not promise a same-day debit the bank cannot honour.
A GoCardless integration project?
Let's talk. 30 minutes to scope mandates and collections, check what the API actually allows and tell you honestly what is feasible.
Discuss my GoCardless project