# Supporting Mandates Set Up Outside of Your Product

Source: https://docs.gocardless.com/docs/partner-integrations/supporting-mandates-set-up-outside-of-your-product

# 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 GoCardless users

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.

  
#### Bulk changes

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

  
#### Mixed usage

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:

  
#### Automated imports

Fetch a list of the user's mandates using the [Mandates API](/docs/api-reference/mandate), 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.

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

> **Tip:**
> We recommend automated imports — this makes it as easy as possible for your customers to get set
>   up and get the best value from your integration, whilst keeping manual administrative work 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.

> **Info: 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:

  
#### [1. Data Retrieval](#phase-1-data-retrieval)

Fetch the merchant's existing mandates and customers from the GoCardless API.

  
#### [2. Tiered Matching](#phase-2-tiered-matching-logic)

Automatically link GoCardless customer records to your platform's user records using a cascading
    match strategy.

  
#### [3. Review & Finalisation](#phase-3-review-and-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](/docs/api-reference/mandate#list-mandates)     |
| List Customers | [Open API / Customer / list_customer](/docs/api-reference/customer#list-customers) |

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.

> **Info: 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

> **Warning: 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

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:

    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](/docs/api-reference/limits#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](/docs/partner-integrations/connect-your-merchants). |

## What's Next?

  
#### [Set up mandates](/docs/partner-integrations/setting-up-mandates)

Create Direct Debit mandates on behalf of your merchant's customers.

  
#### [Webhooks for partners](/docs/partner-integrations/webhooks-for-partners)

Listen for real-time events on mandates, payments, and billing requests.