Importing mandates from another provider

In some cases, your users may also have existing Direct Debit mandates set up outside of GoCardless and wish to manage them together with their GoCardless mandates. The mandate imports API exists to allow integrators to automate this process seamlessly.

Getting set up to import mandates

If you wish to use this feature, you must first have it enabled on your account. To request this, get in touch with your account manager or with our support team and we will respond to your request as soon as possible.

Once the feature is enabled on your account, you can start creating mandate imports. The procedure for using this feature is as follows in outline:

1. Create a mandate import resource
2. Add a collection of data—a mandate import entry—for each mandate you wish to import
3. Submit the import for review

Creating a mandate import

The first step is simple. The only data needed for creating a mandate import is the direct debit scheme the mandates are using. Please note that a mandate import can only include mandates from one direct debit scheme. If you want to transfer mandates in several schemes, you will need one mandate import per scheme.

Please see here for code samples.

Adding mandate import entries

Once we have created the mandate import itself, the next step is to add mandate import entries for each mandate we want to import. To create a mandate import entry, we must provide:

• the ID of the mandate import we are populating
• a customer sub-resource, containing identifying data about the customer to be charged by the mandate (required fields differ between schemes; see the API reference for details)
• a bank_account sub-resource, containing the account holder name bank details (either an IBAN or local details)

For mandates in the SEPA scheme, you must also provide amendment details, which identify the current state of the mandate. See the linked code examples below and the API reference for details.

It is also possible - and recommended - to provide a record_identifier value, a string which should be unique per mandate import. This will make it easier to reconcile the imports with records in your own system later.

Please see here for code samples.

If you provide invalid data, a descriptive error will be returned so you can make corrections.

Please also note that all Mandate Imports have an upper limit of 30,000 entries, so we recommend you split your import into several smaller imports if you’re planning to exceed this threshold.

Submitting the mandate import for review

When all entries have been added to the mandate import, it is time to submit it for review.

In order to defend against possible fraudulent or harmful use of this feature, all submitted imports are subject to review by GoCardless staff. We aim to complete this as quickly as possible.

Please see here for code samples.

Linking up resources

After approval, the mandate import will be processed. As mandates are migrated, you will receive webhooks, just as if they had been created using the mandates API.

If you need to reconcile the new resources with your system, periodically check your mandate import. When its status is processed, listing the mandate import entries will give you the identifiers for the customer, bank account and mandate resources that were created for each mandate import entry.

Please see here for code samples.

It's also worth noting that if you need to cancel a mandate import for any reason, you can use the provided cancellation API. Please note that once a submitted mandate import has been approved by our team, it can no longer be cancelled or reversed.