Partners: Supporting mandates set up outside of your product

To provide the best experience, you should consider allowing your users to “import” mandates set up outside your product so they can bill their customers within your product. There are three reasons why your users might have mandates in this situation:

• Existing users of GoCardless: It’s likely that some of your users will have already been using GoCardless before connecting it to your product, so they may already have Direct Debit mandates set up with their customers.

• Bulk changes: If your user was previously using Direct Debit through another provider, they, subject to availability, can “bulk change” their existing mandates from their existing provider to GoCardless.

• Mixing and matching ways of using GoCardless: Your users might choose to add customers using our Dashboard, our API (for example on their website) or using another integration to better match their workflow.

You can support importing mandates in two main ways:

• Automated imports: Fetch a list of the user’s mandates using the Mandates API, then match the customers’ personal details (given_name, family_name, company_number and email) against your application’s internal records to automatically suggest matches, allowing the user to approve these pairings or manually correct them if incorrect (see below for more detailed instructions)

• Manual imports: Allow users to export a list of customers from your product as a spreadsheet, fill in the mandate IDs from GoCardless, and then upload the completed spreadsheet or email it back to you so you can update your internal records

We recommend supporting automated imports - this makes it as easy as possible for your customers to get set up and then get the best value out of your integration, whilst keeping manual administrative work for you to a minimum.

Building automatic mandate matching

Automatically loading and matching existing Direct Debit mandates provides the best customer experience, making importing your users’ existing customers an easy and integrated part of the process of connecting GoCardless to your product.

This guide walks through how to pull those mandates into your platform and allow the merchant to link them to the right customer records, so payments can be collected without requiring your merchants’ customers to re-authorise.

Overview

The mandate migration process has three phases:

• Data Retrieval — Fetch the merchant’s existing mandates and customers from the GoCardless API.

• Tiered Matching — Automatically link GoCardless customer records to your platform’s user records using a cascading match strategy.

• Review & Finalisation — Present a sync summary to the merchant, allow manual resolution of any unmatched records, and store the resulting mandate_id links.

Phase 1: Data retrieval

When a merchant clicks “Sync Existing Mandates” after connecting via OAuth, your platform should immediately fetch their mandates and customers in parallel using their saved access token. See the following Open API reference links for example requests in languages we offer client libraries in, as well as example JSON responses.

Your platform should consolidate these two responses, joining on mandates[].links.customer = customers[].id, to build a unified list of mandate-and-customer records read for matching.

Phase 2: Examples of Tiered matching logic

Once the data is retrieved, run automated matching in the background. The matching logic is tiered — each tier is attempted in order, and the first successful match wins. Unresolved records fall through to the next tier.

Tier 1 — Exact email match

Compare customer.email (GoCardless) against user.email (your platform). This is the highest-confidence match and will resolve the majority of records. Treat any exact email match as confirmed without requiring merchant review.

Tier 2 — Metadata match

If no email match is found, check whether the GoCardless customer record contains a partner_id in its metadata field that corresponds to a user ID in your platform.

Tier 3 — Fuzzy name and postal code match

If neither of the above tiers produces a match, attempt a fuzzy match on the combination of the customer’s full name and postal code.

Fuzzy matches should be surfaced in the sync summary as “Probable matches” rather than confirmed auto-matches. The merchant should review and confirm these before they are finalised.

Records that fail all three tiers are marked “Unresolved” and require manual pairing.

Phase 3: Review and finalisation

Once matching completes, display a sync summary screen to the merchant. This gives them an overview of what was matched automatically and what needs their attention.

Sync summary

Show the merchant a breakdown similar to the following:

Manual review (required)

For any Unresolved or Probable match records, present the merchant with the GoCardless customer details alongside a search or dropdown to select the correct customer from your platform, once auto-matching has taken place.

The merchant should be able to:

• Confirm a suggested probable match

• Reassign a probable match to a different customer record

• Manually pair an unresolved mandate to a customer record

• Skip a mandate if it should not be linked (e.g. a lapsed customer no longer in your platform)

Finalisation

Once the merchant has reviewed outstanding records and clicks “Confirm & Link”, your platform should:

1. Store the gc_mandate_id against the matched customer record in your database.

2. Mark those mandates as available for payment collection.

3. Display a confirmation message to the merchant.

After this point, payments can now be collected! Mandates are linked and available on the relevant customer profiles.

Storing the mandate link

Once confirmed, persist the relationship between your platform’s customer record and the GoCardless mandate ID. At minimum, store:

You can then use the stored gc_mandate_id in subsequent payment creation calls on behalf of the merchant.

Error Handling

Related Guides

Importing mandates from another provider

What's Next

If you don't have any existing mandates to import, it's now time to start creating some.

Start creating mandatesLearn how to set up new mandates for your merchants