Ellipse Gradient for Header

GoCardless Integration Guide

Connect GoCardless bank debit and open-banking payment workflows with enterprise systems through its REST API and signed webhook events.

GoCardless integration options at a glance

GoCardless provides a JSON REST API for Customers, Mandates, Payments, Subscriptions, Payouts, Refunds, Billing Requests, and related resources. Signed webhooks notify integrations about selected mandate, payment, subscription, and payout state changes. API access commonly uses merchant-specific Bearer tokens, while OAuth is available for delegated or multi-merchant applications. List endpoints use cursor-based pagination, and a general-purpose bulk mutation API was not confirmed. Martini can securely call the REST API, validate webhook signatures, orchestrate asynchronous workflows, map payment data, persist cursors and event identifiers, and apply retry-safe reconciliation logic across sandbox and live environments.

Integration pointSupported by GoCardless?Common use casesHow Martini supports it
REST APIsYesManage Customers, Mandates, Payments, Subscriptions, Payouts, Refunds, Billing Requests, and related resources using JSON requests and responses.Martini can consume the GoCardless REST API from workflows, map responses, apply business rules, and expose controlled APIs for downstream applications.
Webhooks and outbound callbacksYesReceive selected mandate, payment, subscription, payout, refund, and failure state notifications asynchronously.Martini can receive webhook requests, validate GoCardless signatures, acknowledge promptly, deduplicate events, and route processing to workflows.
AuthenticationYesAuthenticate API requests with Bearer access tokens; use OAuth for applications connecting on behalf of multiple merchants or organisations.Martini can store tokens and webhook secrets in secure environment configuration and use separate sandbox and live settings.
Cursor-based paginationYesRetrieve complete collections and support incremental synchronization when list endpoints return more data than one request can provide.Martini workflows can follow cursors, persist checkpoints, resume after failures, and control request concurrency.
Bulk and asynchronous processingLimitedGoCardless payment lifecycles are asynchronous and collection endpoints support pagination, but a general-purpose bulk mutation API was not confirmed.Martini can orchestrate controlled batches, persist initial statuses, process later webhook changes, and apply rate-aware retries.
File and attachment APIsNot confirmedNo general-purpose file import or export mechanism was confirmed as a core GoCardless integration method.Martini should use the REST API and payout or event data for operational synchronization and reconciliation rather than assume file exchange.
GraphQL APIsNot confirmedNo official GoCardless GraphQL API was confirmed; REST is the documented programmatic interface.Martini can consume REST endpoints instead of relying on an unconfirmed GraphQL interface.
SOAP APIsNoGoCardless integrations are documented around REST and webhooks rather than SOAP services.Martini should not design a GoCardless SOAP integration without separate vendor confirmation.

How GoCardless exposes data and business events

GoCardless REST APIs

GoCardless exposes a JSON REST API for Customers, Mandates, Payments, Subscriptions, Payouts, Refunds, Billing Requests, and related resources. Requests use authenticated HTTP operations and list endpoints use cursor-based pagination.

Martini implementation pattern

Martini implementation pattern: a workflow calls the required GoCardless endpoint, validates the response, maps resource fields into a canonical model, persists GoCardless identifiers and checkpoints, and sends the result to the target application.

Implementation sequence

Authenticate with a GoCardless Bearer token
Call the required REST resource endpoint
Follow cursor-based pagination when listing resources
Validate the response and resource status
Map fields to the target system
Persist identifiers and synchronization checkpoints

GoCardless Webhooks

GoCardless sends signed webhook notifications for selected resource and payment lifecycle actions, including mandate, payment, subscription, and payout changes. Coverage is event-specific rather than universal.

Martini implementation pattern

Martini implementation pattern: a webhook-consuming workflow validates the GoCardless signature, acknowledges the request promptly, records the event identifier, and asynchronously routes the event according to its resource and action.

Implementation sequence

Receive the GoCardless webhook notification
Validate the signature with the webhook secret
Reject invalid or incomplete requests
Deduplicate the GoCardless event identifier
Acknowledge the notification promptly
Route the event to the appropriate workflow branch

GoCardless asynchronous payment processing

GoCardless API acceptance does not necessarily mean that a payment has been collected. Subsequent state changes can include confirmation, payment, failure, chargeback, refund, or payout activity.

Martini implementation pattern

Martini implementation pattern: the workflow stores the initial resource status and ID, then consumes later webhook events to update downstream systems while applying ordering, idempotency, and retry rules.

Implementation sequence

Create or update the GoCardless resource
Store its identifier and initial status
Receive subsequent lifecycle events
Compare event state with stored state
Apply the valid state transition once
Update the downstream payment or finance record

GoCardless reconciliation retrieval

Scheduled retrieval of Payouts and related payment information supports reconciliation of collections, fees, currencies, settlement dates, and net amounts. GoCardless does not provide a confirmed direct database integration.

Martini implementation pattern

Martini implementation pattern: a scheduled workflow retrieves paginated data, transforms it into accounting structures, compares it with stored transactions, and persists a checkpoint so processing can resume safely.

Implementation sequence

Start the scheduled reconciliation workflow
Load the last stored synchronization checkpoint
Retrieve Payouts and related data with pagination
Map amounts, currencies, fees, and settlement dates
Compare results with previously processed transactions
Write reconciled data and store the new checkpoint

Common GoCardless integration patterns

Pattern 1: Sync customers and mandates to GoCardless

When to use this pattern

Use this pattern when a CRM, billing platform, or subscription application approves a customer for bank debit collection. The flow must retain both GoCardless identifiers and mandate status so later activation, cancellation, or failure events can be applied to the originating system.

Integration direction
Salesforce
Martini
GoCardless
Example Mapping
GoCardless FieldCanonical FieldTarget Field
customer.emailcustomer.emailCustomer.email
customer.company_namecustomer.nameCustomer.company
mandate.schemepaymentMandate.schemeMandate.scheme
mandate.idpaymentMandate.externalIdMandate.id
Martini implementation pattern

A Martini workflow validates the source customer, creates or updates the GoCardless Customer, creates the Mandate where appropriate, stores resource IDs, and returns a canonical status. Webhook branches update the source system when the Mandate becomes active, cancelled, or failed; transient API failures are retried and duplicate mutations use idempotency keys where supported.

Martini capabilities used
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secure environment configuration
  • error handling

Pattern 2: Process recurring subscriptions and payments

When to use this pattern

Use this pattern when a billing platform needs GoCardless to collect recurring payments. It separates the Subscription schedule from the individual Payments generated over time and uses asynchronous events for final collection status.

Integration direction
Chargebee
Martini
GoCardless
Example Mapping
GoCardless FieldCanonical FieldTarget Field
subscription.idsubscription.externalIdSubscription.metadata
subscription.amountrecurring.amountSubscription.amount
subscription.intervalrecurring.frequencySubscription.interval
payment.statuscollection.statusPayment.status
Martini implementation pattern

Martini receives billing context, validates customer and mandate references, creates or updates the GoCardless Subscription, and stores the resulting ID. Signed payment events are deduplicated and mapped back to the billing platform; failed or charged-back Payments are routed through business rules for recovery or review.

Martini capabilities used
  • workflow orchestration
  • API consumption
  • webhook handling
  • data transformation
  • business rules
  • retry-safe processing

Pattern 3: Route payment failures and lifecycle events

When to use this pattern

Use this pattern when downstream applications need timely reactions to payment confirmation, failure, cancellation, chargeback, refund, or mandate events. It is useful for updating customer-facing status, opening operational cases, or initiating recovery processes.

Integration direction
GoCardless
Martini
ServiceNow
Example Mapping
GoCardless FieldCanonical FieldTarget Field
events[].idevent.externalIdIncident.correlationId
events[].actionpayment.lifecycleActionIncident.category
payments[].statuspayment.statusIncident.paymentStatus
payments[].amountpayment.amountIncident.amount
Martini implementation pattern

A Martini webhook workflow verifies the signature, acknowledges quickly, records the event, and routes it by resource and action. It enriches the event from stored identifiers, suppresses duplicate cases, prevents stale events from overwriting newer status, and retries downstream writes with controlled backoff.

Martini capabilities used
  • webhook consumption
  • signature validation
  • event routing
  • mapping
  • deduplication
  • error handling

Pattern 4: Reconcile payouts with finance systems

When to use this pattern

Use this pattern for scheduled accounting reconciliation where payout settlement, payment references, fees, currencies, and net amounts must be compared with internal collections. It avoids assuming a general-purpose GoCardless bulk write or database interface.

Integration direction
GoCardless
Martini
NetSuite
Example Mapping
GoCardless FieldCanonical FieldTarget Field
payout.idsettlement.externalIdPayout.externalId
payout.amountsettlement.grossAmountPayout.grossAmount
payout.currencysettlement.currencyPayout.currency
payout.amount minus feessettlement.netAmountPayout.netAmount
Martini implementation pattern

A scheduled Martini workflow loads its checkpoint, retrieves cursor-paginated Payouts and related payment data, transforms amounts and settlement dates, and writes accounting records. It records processed identifiers, retries transient failures, and sends exceptions for manual reconciliation rather than silently marking incomplete data as settled.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • pagination handling
  • data mapping
  • checkpoint persistence
  • reconciliation rules
  • monitoring

Applications commonly integrated with GoCardless

GoCardless payment and payout data can be coordinated with accounting, billing, CRM, ERP, and operational applications. The exact object mappings depend on each application’s configuration, but Martini can provide a controlled workflow layer for API calls, webhook processing, reconciliation, and error handling.

Application Scenario Direction Martini Pattern
Xero Reconcile GoCardless collections and payouts with invoices, customers, bank transactions, fees, and settlement information in Xero. GoCardless → Martini → Xero Use GoCardless REST resources and webhook events to update Xero payment and reconciliation data, while retaining resource IDs and payout checkpoints for idempotent processing.
QuickBooks Online Match GoCardless payments and payouts to customers, invoices, and accounting entries in QuickBooks Online. QuickBooks Online → Martini → GoCardless Receive customer or invoice context from QuickBooks Online, create or update GoCardless resources, then route payment and payout events back through a Martini workflow for accounting updates.
Salesforce Synchronize payment authorisations, mandate status, collection failures, and customer payment activity with Salesforce records. Salesforce → Martini → GoCardless Use Salesforce customer context to create GoCardless Customers and Mandates, then process signed GoCardless events into Salesforce using mapped identifiers and duplicate-safe updates.
NetSuite Post GoCardless payment, payout, fee, currency, and settlement information into finance and accounts-receivable processes. GoCardless → Martini → NetSuite Schedule paginated retrieval of Payouts and related Payments, transform them into NetSuite accounting structures, and store checkpoints for resumable reconciliation.
Chargebee Use subscription and invoice context to coordinate recurring GoCardless collections and payment-status updates. Chargebee → Martini → GoCardless Orchestrate subscription data from Chargebee into GoCardless Subscriptions, then map payment lifecycle events back to Chargebee with retry-safe state transitions.
Zuora Coordinate subscription billing with GoCardless payment collection and payment-status updates. Zuora → Martini → GoCardless Call GoCardless from workflows driven by Zuora billing context, store the resulting resource IDs, and route webhook outcomes back to Zuora after signature validation and deduplication.
Stripe Reconcile organisations that use Stripe for card payments and GoCardless for bank debit through common finance or reporting processes. GoCardless → Martini → Stripe Treat each provider as a separate source, normalize payment and settlement data in Martini, and send coordinated reporting or reconciliation outputs without assuming a native GoCardless-to-Stripe integration.
ServiceNow Connect payment failures, customer-account events, or payout exceptions to operational cases and service workflows. GoCardless → Martini → ServiceNow Route selected signed GoCardless events through Martini business rules, enrich them with stored account context, and create or update ServiceNow cases with duplicate protection.

How to build a GoCardless integration in Martini

Objective

Configure GoCardless API access and environment separation before building business flows.

Instructions in Martini

  • Store the Bearer access token and webhook secret in secure Martini environment configuration.
  • Configure separate sandbox and live settings, endpoints, and credentials.
  • Use OAuth only where the application requires delegated or multi-merchant access.

Objective

Select an event-driven or scheduled entry point based on the integration use case.

Instructions in Martini

  • Use a webhook-consuming workflow for selected GoCardless lifecycle events.
  • Use a scheduler for payout reconciliation and cursor-based incremental retrieval.
  • Use an API-triggered workflow when a source application initiates a customer, mandate, or subscription operation.

Objective

Acquire GoCardless data while handling authentication, pagination, signatures, and asynchronous states.

Instructions in Martini

  • Call the GoCardless REST API with Bearer authentication.
  • Validate webhook signatures before processing notifications.
  • Follow cursors on list endpoints and persist the checkpoint.
  • Store resource IDs and initial statuses for later event processing.

Objective

Coordinate API calls, event routing, enrichment, and downstream actions in a maintainable Martini workflow.

Instructions in Martini

  • Route events by resource and action.
  • Retrieve current resource state when an event requires additional context.
  • Apply controlled concurrency and backoff for transient failures or throttling.
  • Use reusable workflow logic for common validation and identifier handling.

Objective

Convert GoCardless JSON resources and event payloads into canonical and target-system models.

Instructions in Martini

  • Map Customers, Mandates, Payments, Subscriptions, Payouts, and Events to target objects.
  • Normalize amounts, currencies, dates, statuses, and external identifiers.
  • Retain source identifiers and event IDs for traceability and deduplication.

Objective

Protect payment and reconciliation processes from invalid, duplicate, stale, or incomplete state transitions.

Instructions in Martini

  • Use idempotency keys for supported create or mutation requests.
  • Reject invalid signatures and incomplete required fields.
  • Do not overwrite newer resource status with an older event.
  • Separate payment collection status from payout settlement status.

Common GoCardless data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
CustomersRepresent payers associated with mandates, payments, and other payment resources.CRM, billing platforms, accounting applicationsMartini maps source customer identifiers and contact data, creates or updates Customers through the REST API, and stores the GoCardless customer ID.
MandatesAuthorise GoCardless to collect payments from a customer’s bank account.Billing platforms, CRM, subscription applicationsMartini creates or tracks Mandates, persists their status, and processes activation, cancellation, and failure events idempotently.
PaymentsRepresent individual collections with amount, currency, charge date, status, and mandate relationships.Billing platforms, ERP systems, accounting applicationsMartini creates or updates Payments, stores initial status, and uses webhook events to synchronize later collection, failure, refund, or chargeback states.
SubscriptionsDefine recurring payment schedules that generate Payments over time.Subscription billing platforms, finance systemsMartini maps subscription schedules, retains resource identifiers, and separates subscription lifecycle events from generated payment events.
PayoutsRepresent transfers of collected funds from GoCardless to a merchant’s bank account.Accounting platforms, ERP systems, reconciliation storesMartini retrieves Payouts with cursor pagination, maps settlement dates, currencies, fees, and net amounts, and stores reconciliation checkpoints.
EventsDescribe resource actions and state changes delivered through GoCardless webhook notifications.CRM, billing, finance, case-management systemsMartini verifies signatures, deduplicates event identifiers, routes by resource and action, and prevents stale events from overwriting newer state.

Authentication and security considerations

Bearer tokens and OAuth

GoCardless API requests use Bearer access tokens. OAuth is available for applications that connect on behalf of multiple GoCardless merchants or organisations.

Secrets and environments

Store API tokens, OAuth credentials, webhook secrets, and account settings in Martini environment configuration rather than source code. Keep sandbox and live credentials and webhook endpoints separate.

Webhook verification

GoCardless webhook requests include a signature. Validate the signature with the configured webhook secret before routing or storing the event, and avoid logging secrets or unnecessary sensitive payment data.

Operational considerations for GoCardless integrations

Pagination and rate limits

Follow GoCardless cursor-based pagination and persist synchronization checkpoints. Use controlled concurrency, backoff, and bounded retries for throttling and transient HTTP failures.

Idempotency and event ordering

Use idempotency keys for supported mutations and deduplicate webhook event identifiers. Because events may not be processed in business-action order, compare event metadata and current resource state before applying transitions.

Asynchronous status

An accepted payment request does not necessarily mean collection has completed. Store initial statuses and use later webhook events to distinguish payment collection, failure, chargeback, refund, and payout settlement.

Testing and change management

Test sandbox and live configurations independently. Manage the GoCardless API version explicitly and test changes to resource fields, event actions, status values, and pagination behavior before production release.

Reconciliation and data protection

Reconcile gross amounts, fees, currencies, payment references, settlement dates, and net payout amounts. Limit logs and stored data to what the business process requires and protect personal and financial information.

Why use Martini instead of scripts or point-to-point integrations?

Centralized orchestration

Martini provides a workflow layer for REST calls, signed webhook intake, asynchronous payment processing, reconciliation, and downstream updates instead of scattering logic across scripts.

Maintainable transformations

Mappings, canonical identifiers, business rules, pagination, and state transitions can be managed as reusable integration logic across GoCardless and multiple enterprise applications.

Reliable operations

Martini supports controlled retries, validation, deduplication, checkpointing, monitoring, and environment-specific configuration. These capabilities help integrations recover from transient failures without creating duplicate payments or accounting records.

API-led flexibility

Martini can consume GoCardless APIs and expose controlled APIs to internal systems, allowing payment processes to evolve without creating a separate point-to-point implementation for every application.

Frequently asked questions

How can GoCardless be integrated with enterprise systems?

GoCardless integrates primarily through its JSON REST API and signed webhook notifications. The API manages Customers, Mandates, Payments, Subscriptions, Payouts, Refunds, Billing Requests, and related resources, while webhooks communicate selected asynchronous state changes. Cursor-based pagination supports collection retrieval and reconciliation.

Can Martini integrate with GoCardless?

Yes. Although a native Martini GoCardless connector is not documented in the supplied product context, Martini can consume the GoCardless REST API, receive signed webhook events, orchestrate payment workflows, map data, and synchronize downstream systems.

Do I need a connector to integrate GoCardless with Martini?

No. A dedicated GoCardless connector is not required. Martini can use GoCardless’s confirmed native integration mechanisms, including its REST API, Bearer authentication, signed webhooks, JSON payloads, and cursor-based pagination.

Is there any extra Lonti cost to integrate GoCardless with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate GoCardless. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from GoCardless, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.

Which GoCardless integration methods should an architecture use?

Use the REST API for resource creation, updates, retrieval, and reconciliation, and use signed webhooks for selected asynchronous state changes. GoCardless uses Bearer access tokens, supports OAuth for delegated or multi-merchant applications, and uses cursor-based pagination. No official GoCardless GraphQL or SOAP API was confirmed.

Are GoCardless events and webhooks available?

Yes, GoCardless supports signed webhook notifications for selected mandate, payment, subscription, payout, refund, and failure actions. Coverage is event-specific rather than universal, so the integration should implement only the required documented event types and validate each signature before processing.

How should GoCardless synchronization and payment status be handled?

Create or update the resource through the REST API, store its GoCardless identifier and initial status, then use webhook events to apply later state changes. Scheduled workflows can retrieve paginated Payouts and related data for reconciliation, using persistent checkpoints and idempotent writes.

How does Martini handle GoCardless mapping, errors, and duplicates?

Martini workflows can transform GoCardless JSON into canonical and target-system models, apply business rules, and persist resource and event identifiers. Implementations should validate webhook signatures, use idempotency keys where supported, deduplicate events, handle pagination, retry transient failures with backoff, and prevent stale events from overwriting newer state.

Related Martini documentation

Webhooks

Workflows

Security

Data and reliability

Connect GoCardless with your enterprise systems

Use Martini to build secure, reliable GoCardless integrations for customer and mandate setup, recurring collections, payment event processing, and payout reconciliation.

EXPLORE MARTINI
BOOK A DEMO