GoCardless

GoCardless

GoCardless enables businesses to collect recurring payments directly from customer bank accounts via direct debit across multiple schemes (Bacs, SEPA, ACH, BECS, BECS NZ, PAD, Autogiro, Betalingsservice).

Data Model & Relationships

• Creditor → your merchant account; most integrations have one. Has scheme identifiers, verification status, and linked bank accounts.
• Customer → a payer; has name, email, address, metadata (up to 3 key-value pairs). One customer can have multiple bank accounts.
• Customer Bank Account → linked to a customer; holds masked account details (last 4 digits, bank name, BIC). Disabling cascades to mandates. Created via IBAN or local bank details (account_number + branch_code).
• Mandate → authorization from a customer to debit their bank account. Linked to one bank account and one scheme. Must be active before payments. Has a unique reference (auto-generated or custom).
• Payment → single debit against an active mandate. Amounts in minor units (pence/cents). Linked to mandate and optionally a subscription or instalment schedule. Has charge_date, description, reference.
• Subscription → recurring schedule that auto-creates payments at a set interval (weekly/monthly/yearly) against a mandate. Supports count or end_date limits, day_of_month, and can be paused/resumed.
• Instalment Schedule → payment plan that creates a series of payments with explicit dates or auto-calculated schedule. Linked to a mandate. Status: pending → active → completed (or creation_failed/cancelled/errored).
• Payout → batched transfer of collected funds to your creditor bank account. Contains payout items. Status: pending → paid (or bounced).
• Payout Item → individual payment, refund, or fee within a payout. Types: payment_paid_out, payment_failed, refund, gocardless_fee, etc.
• Refund → reversal of a confirmed/paid_out payment. Deducted from a future payout. Requires total_amount_confirmation safety check.
• Event → immutable audit log entry for every state change across all resources. Filterable by resource_type, action, and date range.
• Redirect Flow → creates a GoCardless-hosted payment page session. Customer visits the URL, enters bank details, authorizes mandate. Completing the flow creates customer + bank account + mandate in one step.
• Billing Request → modern flow for collecting one-off or recurring payments. Tracks customer onboarding through pending → ready_to_fulfil → fulfilled. Supports open banking (Instant Bank Pay) alongside direct debit.
• Webhook → delivery record of event notifications sent to your endpoint. Tracks success/failure, request/response bodies, and supports retry.
• Institution → banking institution for open banking flows (Instant Bank Pay). Has ID, name, icon, and country.
• Scheme Identifier → the name and reference shown on customer bank statements for each scheme (Bacs, SEPA, ACH, Faster Payments).
• Mandate PDF → generated PDF document of a mandate for compliance/records. Returns a temporary download URL.

Entity Relationships

Creditor → Scheme Identifiers (per scheme) Customer → Customer Bank Accounts → Mandates → Payments → Payout Items → Payouts Mandate → Subscriptions (recurring) or Instalment Schedules (payment plans) Payment → Refunds Redirect Flow → creates Customer + Customer Bank Account + Mandate Billing Request → Customer + Mandate + optional Payment

Mandate States

pending_submission → submitted → active (ready for payments) Terminal: failed, cancelled, expired, blocked Bacs mandates can be reinstated after cancellation; SEPA cannot.

Payment States

pending_submission → submitted → confirmed → paid_out Branching: pending_customer_approval, customer_approval_denied Terminal: failed (retryable up to 3x), cancelled, charged_back Cancellation only possible before submitted.

Subscription States

pending_setup → active ↔ paused → finished or cancelled

Instalment Schedule States

pending → active → completed Terminal: creation_failed, cancelled, errored

Billing Request States

pending → ready_to_fulfil → fulfilling → fulfilled Terminal: cancelled

Common Workflows

One-off payment (API-driven)

1. Create customer (email, name, address)
2. Create customer bank account (IBAN or local details, linked to customer)
3. Validate bank details first with bank details lookup (modulus + reachability check)
4. Create mandate against the bank account
5. Wait for mandate to become active (check via get or events)
6. Create payment against the mandate (amount in minor units, use idempotency_key)

One-off payment (hosted page)

1. Create redirect flow (description, session_token, success_redirect_url)
2. Redirect customer to the flow URL
3. Customer enters bank details on GoCardless-hosted page
4. Complete redirect flow (session_token verification) — creates customer + bank account + mandate
5. Create payment against the returned mandate ID

Recurring payments

1. Set up customer + bank account + mandate (via API or redirect flow)
2. Create subscription against the active mandate (amount, currency, interval_unit, interval)
3. GoCardless auto-creates payments at each interval
4. Pause/resume subscription as needed
5. Cancel subscription to stop future payments (pending payments must be cancelled individually)

Payment plan (instalment schedule)

1. Set up customer + bank account + mandate
2. Create instalment schedule — two modes:
   • Explicit dates: provide array of {amount, charge_date} for each payment
   • Auto-schedule: provide total_amount, interval_unit, start_date; GoCardless splits evenly
3. GoCardless creates all payments upfront (status starts as pending)
4. Cancel schedule to stop remaining payments

Reconciliation

1. List payouts filtered by status or date
2. For each payout, list payout items to see individual payments, refunds, and fees
3. Match payout items to source payments/refunds
4. Use events for full audit trail of every state change

Key Gotchas

• Mandate before payment: Payments fail if mandate is not active. For SEPA/BECS/PAD/ACH, mandates only submit when the first payment is due.
• Idempotency keys: Use Idempotency-Key header on payment/refund creation to prevent duplicates on retries.
• Amounts in minor units: 1000 = £10.00 / €10.00. Integer, never float.
• Charge date notice periods: Bacs = 2 working days, SEPA = 6 working days, ACH = varies by SEC code.
• Payout timing: Funds arrive 3-5 business days after payment confirmation, batched daily.
• Refund limits: Can only refund confirmed/paid_out payments. Refund amount <= payment amount minus prior refunds. Requires total_amount_confirmation.
• Reference length: Bacs references max 10 chars, SEPA max 140 chars.
• Disabling bank account: Cascades — cancels all mandates and cancellable payments immediately.
• Subscription cancellation: Does NOT cancel pending payments — cancel them individually.
• GoCardless-Version header: Every request requires GoCardless-Version: 2015-07-06 (handled automatically).
• Response wrapping: All responses are wrapped in a resource key (e.g. {"payments": {...}} or {"payments": [...]}).
• Cursor pagination: List endpoints use cursor-based pagination with after, before, and limit params (max 500). Response includes meta.cursors.after for next page.
• Redirect flow session_token: The same session_token value must be used for create and complete — mismatch causes bad_request error.
• Bank details lookup: If available_debit_schemes is empty, payments cannot be collected from that account.
• Scheme identifier names: Max length varies by scheme (Bacs=18, SEPA=70, ACH=16). Must match legal/trading name to reduce chargeback risk.
• Sandbox vs live: Base URLs differ (api.gocardless.com vs api-sandbox.gocardless.com).
• Metadata: All resources support up to 3 key-value pairs of custom metadata. Keys and values must be strings.