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:
Some of your users will have already been using GoCardless before connecting it to your product, and may already have Direct Debit mandates set up with their customers.
If your user was previously using Direct Debit through another provider, they can "bulk change" their existing mandates from their existing provider to GoCardless (subject to availability).
Your users might choose to add customers using the GoCardless Dashboard, the API, or another integration to better match their workflow.
You can support importing mandates in two main ways:
Fetch a list of the user's mandates using the Mandates API, then
match 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 or correct them.
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.
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:
Fetch the merchant's existing mandates and customers from the GoCardless API.
Automatically link GoCardless customer records to your platform's user records using a cascading match strategy.
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.
| Request | Reference |
|---|---|
| List Mandates | Open API / Mandate / list_mandate |
| List Customers | Open API / Customer / list_customer |
Your platform should consolidate these two responses, joining on mandates[].links.customer = customers[].id, to build a unified list of mandate-and-customer records ready for matching.
Phase 2: 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:
| Status | Count | Action Required |
|---|---|---|
| Auto-matched | 85 | The Merchant confirms they are correct and confirms the auto-match |
| Probable matches | 6 | The merchant should review and confirm or reassign |
| Unresolved | 5 | The merchant must manually pair with a customer record |
Manual review
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.
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:
- Store the
gc_mandate_idagainst the matched customer record in your database. - Mark those mandates as available for payment collection.
- 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:
| Field | Description |
|---|---|
platform_user_id | Your internal customer identifier |
gc_mandate_id | The GoCardless mandate ID (e.g. MD123ABC) |
gc_customer_id | The GoCardless customer ID (e.g. CU123ABC) |
match_method | How the match was made: email, metadata, fuzzy, or manual |
linked_at | Timestamp of when the link was confirmed |
You can then use the stored gc_mandate_id in subsequent payment creation calls on behalf of the merchant.
Error handling#
| Scenario | Recommendation |
|---|---|
| API rate limit hit during retrieval | Implement exponential backoff and retry. See rate limiting. |
| Mandate status is not active | Exclude cancelled, expired, and failed mandates from the sync. Only surface active and pending_submission mandates. |
| Merchant has no existing mandates | Show an empty state ā do not surface the manual pairing UI. |
| OAuth token missing or expired | Redirect the merchant to reconnect via OAuth before proceeding. See Connect your merchants. |