Failed Payment Recovery for GoCardless

How this pack fits GoCardless

GoCardless uses a webhook-driven model: payment events (failed, late_failure, charged_back) arrive as webhooks with cause codes that explain why a payment did not succeed. The pack's classification rules map each cause code to a recovery pathway — automatic retry, customer outreach, or manual review. This gives your team a structured response instead of ad-hoc firefighting.

GoCardless objects and data this pack uses

• Payment events: failed, late_failure, charged_back — each with a cause code (e.g. insufficient_funds, bank_account_closed, mandate_cancelled)
• Mandates: status and history used to determine whether a retry or re-authorisation is needed
• Customer records: email, name, and associated mandates for outreach workflows
• Webhook payloads: the full event object including links to payment, mandate, and subscription resources
• Retry metadata: retry count, last retry date, and next scheduled retry stored in your application database
• Subscription records: used to identify recurring payment context and calculate revenue at risk

Workflow steps

1. 1

   Webhook receipt and event parsing

   Your application receives a GoCardless webhook, validates the signature, and extracts the event type, cause code, and linked resource IDs.

2. 2

   Failure classification

   The pack's classification rules map the cause code to a recovery category. The event is logged in your database with the classification result.

3. 3

   Retry scheduling or outreach

   Retryable failures are scheduled for a retry via the GoCardless API, respecting Direct Debit timing rules. Non-retryable failures trigger a customer email or support ticket.

4. 4

   Customer communication

   Templated emails or SMS messages inform the customer of the issue and next steps. The tone and urgency vary by failure type and customer history.

5. 5

   Resolution tracking and escalation

   Each failure is tracked through to resolution (successful retry, new mandate, or write-off). Failures that exceed retry limits or remain unresolved after a defined period are escalated.

Decision and escalation logic for GoCardless

• The pack's classification logic maps the cause to a recovery category: retryable (e.g. insufficient_funds), non-retryable (e.g. bank_account_closed), or disputed (charged_back)
• For retryable failures, the workflow checks retry count and schedules the next attempt with back-off timing aligned to Direct Debit cycle constraints
• Non-retryable failures trigger a customer outreach workflow requesting updated bank details or a new mandate
• Charged-back payments are flagged for manual review with full event history attached
• High-value failures or failures on long-standing mandates are escalated to a senior team member

Implementation considerations

• Store payment failure events in your database with the full webhook payload. The cause code alone is not enough — you need the linked mandate and subscription data for context.
• Use GoCardless's sandbox environment to simulate failure scenarios before deploying. Test each cause code path to verify classification and routing.
• Coordinate retry timing with GoCardless's own retry schedule if you have their "intelligent retries" feature enabled. Doubling up retries wastes Direct Debit attempts.
• Direct Debit has longer settlement cycles than card payments. Build reporting that accounts for the 3–5 day confirmation window.
• If you use GoCardless with a billing platform (e.g. Chargebee, Zuora), ensure the pack webhook handler does not conflict with the platform connector.

Frequently asked questions

Related pages