A GoCardless API request can create a mandate, payment or subscription. A dependable integration must also follow every later event, protect the link to the customer and invoice, handle failure safely and explain the final payout to finance.
01
The first payment request is the easy part
Imagine a maintenance company that collects monthly service plan fees. Its team raises invoices in one system, checks GoCardless in another and marks customer accounts as paid by hand. The process works while volumes are modest and the same person remembers every exception.
The company then adds more plans, more customers and several people who need an accurate payment status. A failed collection can leave an invoice looking paid. A cancelled mandate can remain attached to an active agreement. The amount that reaches the bank may not match one neat batch of invoices because fees, refunds or late failures have changed the payout.
Connecting the GoCardless API can remove much of that manual work, but only if the integration covers the complete payment lifecycle. Creating a customer and sending a payment request is not the finish line. The application must keep listening after the customer leaves the payment page.
This guide explains the parts a GoCardless developer needs to design around the API: business references, customer authorisation, mandates, payment states, webhooks, recovery and payout reconciliation. The aim is not clever payment code. It is a payment operation the wider business can trust.
02
What the GoCardless API is designed to do
GoCardless provides a REST API for collecting bank payments. Its developer platform supports one-off payments, subscriptions and instalment schedules, with a sandbox for end to end testing and official client libraries for several common programming languages, including PHP, Java, Ruby, Python and .NET.
The API exposes the resources needed to build a payment operation. These include customers, customer bank accounts, mandates, payments, subscriptions, refunds, payouts, payout items and events. Billing Requests and hosted flows can collect the authorisation needed before a payment is created.
That resource model is useful because bank payments have a lifecycle. A mandate gives permission to collect. A payment moves through states over time. A subscription creates later payments. A payout groups money that has reached the business, including adjustments that may not match the original collection list exactly.
GoCardless says one integration can collect payments across more than 30 countries. International reach may be useful, but it does not make every scheme behave identically. Currency, authorisation, settlement timing and customer notification requirements still need to be understood for the countries the business actually serves.
03
Start with the business record, not the API object
Return to the maintenance company. Its important records are the customer, service agreement, invoice and account status. Those records existed before GoCardless and should remain meaningful if the payment provider changes later.
The integration should therefore store GoCardless identifiers beside the business identifiers rather than replacing them. A customer may have a GoCardless customer ID, bank account ID and mandate ID. An invoice or collection instruction may have a payment ID. A service plan may have a subscription ID.
Metadata can carry a short internal reference into the payment platform, but the business application should still keep its own proper relationship table. A reference such as an invoice number is useful when support searches a dashboard or finance investigates a payout. It is not a substitute for a local model that records which provider resource belongs to which customer and agreement.
Think about ownership before writing the first request. Which system owns the invoice amount? Which system decides when service begins? Which status should staff see while a bank payment is still being processed? What should happen if a mandate is cancelled? Clear answers prevent two systems from silently becoming competing sources of truth.
04
Model the payment lifecycle in business language
Payment provider terminology is precise, but most colleagues should not need to memorise it. The application can translate technical states into plain operational language without hiding the provider detail needed for support.
A payment created successfully is not necessarily money in the bank. The application might show it as scheduled or processing. A later event can confirm collection, report failure or connect it to a payout. The business action should match the confidence available at that point.
| GoCardless resource | Business meaning | What not to assume |
|---|---|---|
| Customer | The payer profile linked to your customer record | One provider customer always equals one commercial account |
| Customer bank account | The account used for a bank payment mandate | Bank details should be copied into your own database |
| Mandate | The customer's authorisation for future collections | A created mandate is already active and will remain active forever |
| Payment | One collection instruction and its changing status | A successful API response means the invoice is paid |
| Subscription | A rule that creates recurring payments | The subscription itself proves every payment succeeded |
| Event | A notification that something changed | The same event will arrive once and in a convenient order |
| Payout | A transfer of net funds to the business bank account | The total equals a simple batch of your own successful payments |
| Payout item | One credit or debit within a payout | Only original payments affect the amount received |
For the maintenance company, access to a non-critical monthly service might continue while a collection is pending. A large installation deposit may need a firmer confirmation before work is booked. The API status is the same technical fact, but the commercial rule around it can differ.
05
Let the customer authorise through the right flow
A bank payment begins with permission. GoCardless provides hosted payment pages and Billing Request Flows that can collect the information and authorisation required for the payment method. It also supports more customised page options where the integration and compliance requirements justify them.
For many businesses, a hosted flow is the sensible starting point. It keeps the sensitive payment entry journey with the provider and reduces the amount of payment handling the application must own. The local system creates the flow, sends the customer to the secure page and records the resulting provider references when the flow completes.
Do not use the customer returning to your success URL as the only proof that setup worked. A browser can close, a connection can fail or a user can revisit an old page. The application should confirm the provider resource and then rely on later events for changes to the mandate.
A mandate can move through states such as pending submission, submitted, active, failed, cancelled or expired. The local record should retain that state and the last relevant event. If GoCardless reports that a mandate was replaced, the integration must keep the new identifier connected to the same customer and agreement rather than leaving future collections attached to the retired record.
06
Use webhooks as operational input, not background noise
GoCardless sends webhooks to report changes such as a payment failure, a cancelled mandate or a newly created payment from a subscription. These notifications are how the business application stays current without repeatedly asking the API for every resource.
The first job of a webhook endpoint is to verify the signature in the Webhook-Signature header. GoCardless documents that the signature should be calculated from the original request body and the endpoint secret. If it does not match, the request should not be trusted.
A webhook body can contain several events. Each event has an ID, a resource type, an action and details explaining the change. The handler should record the event ID before changing business data so the same event cannot apply the same action twice. GoCardless explicitly recommends keeping a record of processed events to avoid double processing.
Keep the HTTP response quick. Validate the signature, store the event and hand the business work to a queue. The queue can retrieve any fresh provider data, update local records, create a task or notify the right person. This stops a large batch of events from making the webhook endpoint time out.
Idempotency is essential. If a repeated event says a mandate was cancelled, the second attempt should find the cancellation already applied and finish harmlessly. It must not suspend the account twice, send several contradictory messages or create duplicate finance work.
07
Failed payments need a controlled recovery path
Failure is normal enough to deserve its own workflow. A bank payment can fail because of insufficient funds, an invalid account or a change reported later by the bank. The application should not turn every failure into a vague red badge and leave staff to investigate from scratch.
The provider event can update the payment record, retain the reason and place the account into an agreed recovery route. That route may schedule an approved retry, ask the customer to update their details, notify finance or pause a service after a defined period. The exact action is a business policy, not something the controller should invent.
Prevent duplicate collections by giving each intended payment a stable local identity. If a request times out, check whether the provider resource already exists before sending another instruction. The user should be able to see that the system is verifying an uncertain result rather than pressing a button that may collect twice.
Late failures and chargebacks matter because an earlier status may have looked successful. Keep the original payment linked to every adjustment and show the latest authoritative state. Hiding the history behind one editable status makes support faster for five minutes and reconciliation harder for years.
08
Reconciliation is where the integration proves its value
Finance does not reconcile individual API requests to the bank. It reconciles payouts. GoCardless generally creates payouts on working days for each currency, and a payout can contain credits and debits rather than a clean list of successful payments.
The Payout Items API exposes the transactions that make up a payout. Credits can represent collected payments. Debits can represent fees, refunds, chargebacks or a payment that appeared successful before the bank reported a late failure. The net of those items explains the amount transferred.
A payout may also contain payments created outside your integration if the same GoCardless account is used through another integration or the dashboard. Code that assumes every item originated in the local application will eventually meet a payment it cannot find.
The maintenance company should import the payout and its items, link each known payment to its invoice, record adjustments separately and flag unmatched items for review. Finance can then explain the bank deposit from evidence rather than exporting several CSV files and rebuilding the answer by hand.
This is the difference between payment automation and payment visibility. Automation creates collections. Visibility lets the business prove which invoices were collected, which amounts changed and why the bank received the final total.
09
Test the awkward cases in the sandbox
GoCardless provides a sandbox and scenario tools so an integration can be exercised without moving real money. Use that environment for more than the happy path.
Create a customer and complete the authorisation journey. Let a subscription generate a payment. Simulate a failure, cancellation, refund and payout. Send the same webhook event twice. Send several events in one request. Delay the worker that processes them. Confirm that the application remains understandable when events arrive while a user is viewing the account.
Test recovery as well as creation. Rotate a sandbox secret. Temporarily break the queue. Replay stored events. Remove a local relationship and see whether monitoring spots an unmatched provider record. Make sure an operator can diagnose the problem without database access.
A useful acceptance test is written in business language: given an active service agreement, when the customer cancels the mandate at their bank, then the account shows the cancellation, future collection is stopped and the named team receives one task. The API call is only one step inside that result.
10
Security and support need deliberate boundaries
Store live access tokens and webhook secrets in a proper secret store or protected environment configuration. Do not commit them to source control, include them in screenshots or expose them to browser code. Separate sandbox and live credentials so a development mistake cannot reach real customer payments.
Use the smallest operational access each person needs. Support may need to view payment history and resend an authorisation link. Finance may need payouts and refunds. Only a smaller group should change integration settings or issue high value actions. Record important manual decisions in an audit trail.
Log provider IDs, internal references, event IDs and safe status information. Do not fill logs with customer bank data or full webhook bodies unless there is a defined, protected need. Useful observability answers which payment failed and which event changed it without turning the log platform into another sensitive database.
Monitoring should cover missing business outcomes. Alert on repeated signature failures, a growing webhook queue, events that cannot find a local record, payments stuck in an unexpected state and payouts that do not reconcile. An endpoint returning 200 is not proof that finance can trust the result.
11
Build the smallest complete GoCardless integration
The smallest useful integration is not the one with the fewest endpoints. It is the one that completes one real business journey safely.
For the maintenance company, that could mean hosted customer authorisation, one monthly service plan, verified webhook processing, visible failures and payout reconciliation back to the invoice. Refund tools, international schemes and more complex billing can follow when the core journey is proven.
Draw the lifecycle before estimating the work. Mark the system of record, provider resources, events, human decisions and accounting outcome. This exposes the less glamorous tasks that decide whether the integration will survive production: duplicate protection, retries, monitoring, access and support screens.
GoCardless provides a clear API, sandbox and hosted payment journeys. The developer still has to connect them to the operation around the payment. When that connection is designed properly, staff stop copying statuses between systems and customers receive a more consistent answer about what has happened.
DanJMills helps businesses integrate payment providers with the software, portals and internal workflows they already use. If GoCardless works in isolation but invoicing, customer access, failures or payout reconciliation still depend on manual updates, an API integration review can define the data, events and controls needed to make the full process dependable.
Useful questions
Before a GoCardless integration goes live, confirm:
- Every GoCardless customer, mandate, payment and subscription links to a clear internal record.
- The customer authorisation journey uses an appropriate hosted or compliant payment flow.
- Payment creation does not mark an invoice as paid before the required provider event.
- Webhook signatures are verified against the original request body.
- Processed event IDs are stored so repeated notifications are harmless.
- Webhook processing is queued, monitored and safe when a request contains several events.
- Mandate cancellation, replacement, failure and expiry update the wider customer workflow.
- Failed payments have an agreed retry, communication and ownership policy.
- Payout items reconcile credits, fees, refunds, chargebacks and late failures to the bank total.
- Unmatched provider records and stalled events create visible operational alerts.
- Sandbox tests cover duplicate events, cancellations, failures, refunds and payouts.
- Live tokens and webhook secrets are protected, rotated and kept out of source control.
