Skip to content

Integrating GoCardless

Auth: API key · Partner program: not required · Setup time: about 10 minutes · Last verified: 2026-05-15

Direct-debit + bank-payment gateway. Primary in UK / EU SEPA / Australia BECS; mandates are first-class.

api_key (long-lived access token). Submit it via the Connect Link form; the adapter sets Authorization: Bearer <token>.

GoCardless also offers OAuth for partner apps (“OAuth allows you to act on behalf of other GoCardless accounts”, https://docs.gocardless.com/docs/api-reference/oauth-reference). OpenSteward does not implement that partner-app flow: the access token above is the only way to connect.

  1. Sign in at https://manage.gocardless.com (live) or https://manage-sandbox.gocardless.com (sandbox).
  2. Developers → Access tokens, generate a token, copy it.
  3. Open /platforms → Payments → GoCardless → Configure and submit:
    • accessToken
    • environment — live or sandbox

Configure at Developers → Webhook endpoints. Subscribe to:

  • payments, refunds, subscriptions, mandates, payouts, customers

The adapter verifies the Webhook-Signature header (HMAC-SHA-256 of the raw body with the endpoint’s secret).

  • Mandate is the canonical PaymentMethod for direct-debit semantics. The adapter surfaces mandates as PaymentMethod rows with type: 'mandate' and stores the bank-account detail under metadata.
  • Payment lifecycle is multi-step. pending_submission → pending_customer_approval → submitted → confirmed → paid_out. The adapter maps each to the canonical ChargeStatus.
  • No Dispute resource — chargebacks emerge as payment.failed with cause = chargeback.
  • GoCardless-Version header is pinned to 2015-07-06 (the stable API version).