# 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](https://manage.gocardless.com/), 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](https://developer.gocardless.com/api-reference/#mandates-list-mandates), 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.

> **Note** This flow is triggered at the point of OAuth connection and runs in the background. It should be invisible to the merchant’s end customers.

### 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.

| Request        | Reference                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| List Mandates  | [Open API / Mandate / list_mandate](https://developer.gocardless.com/api-reference/openapi/#tag/Mandate/operation/list_mandate)     |
| List Customers | [Open API / Customer / list_customer](https://developer.gocardless.com/api-reference/openapi/#tag/Customer/operation/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 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.

> **Note** This process runs entirely server-side and should complete before the sync summary is shown to the merchant.

#### 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.

```json
GC customer.email == Platform user.email

→  Auto-matched ✓
```

#### Tier 2 — Metadata match

> **Prerequisite** This tiered approach only works if your customer has input a unique identification number against their customers on GoCardless.

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.

```json
GC customer.metadata['partner_id'] == Platform user.id

→  Auto-matched ✓
```

#### 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.

```json
GC (given_name + family_name + postal_code) ≈ Platform (name + postal_code)

→  Probable match, flagged for review
```

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 (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:

| 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](https://developer.gocardless.com/api-reference/#making-requests-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.                                                  |

## Related Guides

## What's Next

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