Direct Debit: Importing Mandates
Importing mandates from another provider
So far, we have discussed ways to help your users set up new recurring payments, add information about new customers and so on.
However, your users may also have existing direct debit mandates set up 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 merchant 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:
Wait until a member of the GoCardless team approves the import, at which point the mandates will be created
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, the one specified here. If you want to transfer mandates in several schemes, you will need one mandate import per scheme.
1$client = new \GoCardlessPro\Client(array(
2 'access_token' => 'your_access_token_here',
3 'environment' => \GoCardlessPro\Environment::SANDBOX
4));
5
6$mandateImport = $client->mandateImports()->create([
7 "params" => ["scheme" => "sepa_core"]
8]);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
customersub-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_accountsub-resource, containing the account holder's 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 code examples below and the API reference for details.
It is also possible - and recommended - to provide a record_identifier value, a string that should be unique per mandate import. This will make it easier to reconcile the imports with records in your own system later.
1$mandateImportEntry = $client->mandateImportEntries()->create([
2 "params" => [
3 "links" => [
4 "mandate_import" => $mandateImport->id
5 ],
6 "record_identifier" => "bank-file.xml/line-1",
7 "customer" => [
8 "company_name" => "Théâtre du Palais-Royal",
9 "email" => "moliere@tdpr.fr"
10 ],
11 "bank_account" => [
12 "account_holder_name" => "Jean-Baptiste Poquelin",
13 "iban" => "FR14BARC20000055779911"
14 ],
15 // Amendment details are required for SEPA only
16 "amendment" => [
17 "original_mandate_reference" => "REFNMANDATE",
18 "original_creditor_id" => "FR123OTHERBANK",
19 "original_creditor_name" => "Amphitryon"
20 ]
21 ]
22]);If you provide invalid data, a descriptive error will be returned so you can make corrections.
Submitting the mandate import for review
When all entries have been added to the mandate import, it is time to submit them for review.
In order to defend against the 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.
1$client->mandateImports()->submit($mandateImport->id);
2Linking 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.
1$mandateImport = $client->mandateImports()->get(mandateImport->id);
2
3if ($mandateImport->status === "processed") {
4 doReconciliation();
5}1$entries = $client->mandateImportEntries()->all([
2 "params" => ["mandate_import" => "IM000010790WX1"]
3]);
4
5foreach ($entries as $i => $entry) {
6 echo $entry->record_identifier;
7 echo $entry->links->customer;
8 echo $entry->links->customer_bank_account;
9 echo $entry->links->mandate;
10}