GoCardless Integration

GoCardless is a global leader in bank-to-bank payments, specializing in Direct Debit (ACH, BACS, SEPA, and more). LostChurn connects to GoCardless via OAuth and processes webhook events to recover failed Direct Debit payments, which have unique failure modes compared to card payments.

Prerequisites

• An active GoCardless account (Standard, Plus, or Pro)
• Access to the GoCardless Dashboard with admin permissions
• A LostChurn account with at least one workspace created

Connection Steps

LostChurn connects to GoCardless using OAuth for a streamlined setup experience.

1. In your LostChurn dashboard, go to Settings > Integrations and click Connect GoCardless.
2. You will be redirected to GoCardless's authorization page. Log in with your GoCardless account credentials.
3. Review the permissions LostChurn is requesting:
   • Payments: Read and create
   • Mandates: Read
   • Subscriptions: Read and manage
   • Events: Read
   • Webhooks: Manage
4. Click Allow access.
5. You are redirected back to LostChurn with OAuth tokens configured.
6. LostChurn automatically registers a webhook endpoint with GoCardless.

Alternative: Access Token

If you prefer manual credential management:

1. In the GoCardless Dashboard, go to Developers > Create > Access Token.
2. Select Read-Write access.
3. Name the token LostChurn and create it. Copy the token immediately.
4. In your LostChurn dashboard, select Connect with Access Token on the GoCardless integration page.
5. Select your environment (Sandbox or Live), paste the access token, and click Save and Verify.

Webhook Configuration

If you connected via OAuth, webhooks are configured automatically. For manual connections:

1. In the GoCardless Dashboard, go to Developers > Create > Webhook Endpoint.
2. Set the URL to:

   https://webhooks.lostchurn.com/v1/gocardless

3. GoCardless generates a Webhook Secret for this endpoint. Copy it.
4. In your LostChurn dashboard, paste the webhook secret into the Webhook Secret field on the GoCardless integration page.

GoCardless sends all event types to a single webhook endpoint (there is no per-event subscription). LostChurn filters and processes only the relevant events listed below.

Webhook Signature Verification

GoCardless signs webhook payloads with HMAC-SHA256 using the webhook secret. The hex-encoded signature is sent in the Webhook-Signature HTTP header. LostChurn computes HMAC-SHA256 of the raw request body using your webhook secret and compares the hex digest against the Webhook-Signature value using a timing-safe comparison. Requests with missing or invalid signatures are rejected with a 401 response.

Verify Connection

1. GoCardless does not provide a built-in "send test webhook" button in the dashboard.
2. To verify the connection, create a test mandate and payment in your GoCardless sandbox:
   • Log in to the GoCardless Sandbox Dashboard.
   • Create a test customer and mandate using GoCardless's redirect flow.
   • Create a payment against the mandate.
   • In the sandbox, you can simulate payment failure by navigating to the payment and clicking Simulate failure.
3. In your LostChurn dashboard, navigate to Events and confirm the payment failure event appears.

A successful connection shows a green Connected badge on the GoCardless card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Direct Debit vs. Card Payments

Direct Debit payments (ACH, BACS, SEPA) have fundamentally different failure characteristics compared to card payments:

• Delayed failures: Unlike card payments that decline instantly, Direct Debit payments can fail days after submission. BACS payments can fail up to 5 business days after submission. SEPA payments can fail up to 8 weeks after collection. LostChurn accounts for these delays in its retry scheduling.
• Late failures: Some Direct Debit schemes allow customers to reverse payments weeks or months after collection (e.g., SEPA Direct Debit Core allows reversals within 8 weeks, or 13 months for unauthorized mandates).
• Mandate-based: Direct Debit requires an active mandate (authorization) from the customer. If the mandate is cancelled, no further payments can be collected without establishing a new one.

LostChurn's retry and dunning strategies are specifically tuned for Direct Debit timing and failure modes.

Supported Schemes

GoCardless supports multiple Direct Debit schemes. LostChurn handles all of them:

Retry timing is adjusted per scheme to account for the different settlement and failure windows.

Failure Reasons

GoCardless provides specific failure reason codes. LostChurn maps these to recovery actions:

• insufficient_funds: Retry after a delay (typically 5-7 business days to align with the next pay cycle).
• bank_account_closed: Trigger dunning email asking the customer to set up a new mandate.
• mandate_cancelled: Trigger dunning flow to re-establish a mandate.
• refer_to_payer: Contact the customer's bank; retry after delay.
• direct_debit_not_enabled: Customer's bank account does not support Direct Debit; trigger alternative payment method request.
• bank_account_transferred: Account transferred to a new bank; trigger mandate update flow.

Sandbox Environment

GoCardless provides a sandbox environment at manage-sandbox.gocardless.com. Sandbox transactions simulate the full Direct Debit lifecycle including settlement delays and failure scenarios. LostChurn labels sandbox events with a sandbox badge.

Idempotency

GoCardless enforces idempotency keys on payment creation requests. LostChurn generates deterministic idempotency keys based on the subscription and payment period to prevent duplicate charges during retries.

Rate Limits

GoCardless enforces rate limits of 1,000 requests per minute. LostChurn distributes retry requests across time windows to stay within this limit. If your account has custom rate limits, contact LostChurn support to adjust throughput settings.

Automatic Payment Retry

LostChurn can automatically retry failed Direct Debit payments by creating a new payment against the existing mandate. Key details:

• Retry method: Creates a new GoCardless payment via POST /payments with the original mandate ID.
• Charge date: Automatically calculated based on the Direct Debit scheme (BACS: 3 business days, SEPA: 2 business days, ACH: 2 business days).
• Retry eligibility: Only payments that failed due to retryable reasons (e.g., insufficient_funds, refer_to_payer) are automatically retried. Non-retryable failures (e.g., bank_account_closed, mandate_cancelled) trigger dunning campaigns instead.
• Mandate validation: LostChurn verifies the mandate is still active before attempting a retry. If the mandate has been cancelled or failed, the system falls back to dunning communications.
• Idempotency: Each retry uses a deterministic idempotency key to prevent duplicate payments.

GoCardless + Stripe/Chargebee

Many businesses use GoCardless alongside another payment processor (e.g., Stripe for cards and GoCardless for Direct Debit). LostChurn supports this multi-provider configuration, with events from each provider processed independently. The unified analytics dashboard shows recovery metrics across all connected providers.