Mandate Import Entry

View as Markdown

Mandate Import Entries are added to a Mandate Import. Each entry corresponds to one mandate to be imported into GoCardless.

To import a mandate you will need:

Identifying information about the customer (name/company and address)
Bank account details, consisting of an account holder name and either an IBAN or local bank details
Amendment details (SEPA only)

We suggest you provide a record_identifier (which is unique within the context of a single mandate import) to help you to identify mandates that have been created once the import has been processed by GoCardless. You can list the mandate import entries, match them up in your system using the record_identifier, and look at the links fields to find the mandate, customer and customer bank account that have been imported.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

Add a mandate import entry#

POST/mandate_import_entries

For an existing mandate import, this endpoint can be used to add individual mandates to be imported into GoCardless.

You can add no more than 30,000 rows to a single mandate import. If you attempt to go over this limit, the API will return a record_limit_exceeded error.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/mandate_import_entries HTTP/1.1
Content-Type: application/json
{
  "mandate_import_entries": {
    "links": {
      "mandate_import": "IM000010790WX1"
    },
    "record_identifier": "bank-file.xml/line-1",
    "customer": {
      "company_name": "Jane's widgets",
      "email": "jane@janeswidgets.fr"
    },
    "bank_account": {
      "account_holder_name": "Jane Doe",
      "iban": "FR14BARC20000055779911"
    },
    "amendment": {
      "original_mandate_reference": "REFNMANDATE",
      "original_creditor_id": "FR123OTHERBANK",
      "original_creditor_name": "Existing DD Provider"
    }
  }
}

@client.mandate_import_entries.create(params: {
  links: {
    mandate_import: "IM000010790WX1"
  },
  record_identifier: "bank-file.xml/line-1",
  customer: {
    company_name: "Jane's widgets",
    email: "jane@janeswidgets.fr"
  },
  bank_account: {
    account_holder_name: "Jane Doe",
    iban: "FR14BARC20000055779911"
  },
  amendment: {
    original_mandate_reference: "REFNMANDATE",
    original_creditor_id: "FR123OTHERBANK",
    original_creditor_name: "Existing DD Provider"
  }
})

client.mandate_import_entries.create(params={
  "links": {
    "mandate_import": "IM000010790WX1"
  },
  "record_identifier": "bank-file.xml/line-1",
  "customer": {
    "company_name": "Jane's widgets",
    "email": "jane@janeswidgets.fr"
  },
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "iban": "FR14BARC20000055779911"
  },
  "amendment": {
    "original_mandate_reference": "REFNMANDATE",
    "original_creditor_id": "FR123OTHERBANK",
    "original_creditor_name": "Existing DD Provider"
  }
})

const mandateImportEntry = await client.mandateImportEntries.create({
  links: {
    mandate_import: "IM000010790WX1"
  },
  record_identifier: "bank-file.xml/line-1",
  customer: {
    company_name: "Jane's widgets",
    email: "jane@janeswidgets.fr"
  },
  bank_account: {
    account_holder_name: "Jane Doe",
    iban: "FR14BARC20000055779911"
  },
  amendment: {
    original_mandate_reference: "REFNMANDATE",
    original_creditor_id: "FR123OTHERBANK",
    original_creditor_name: "Existing DD Provider"
  }
});

$client->mandateImportEntries()->create([
  "params" => [
    "links" => [
      "mandate_import" => "IM000010790WX1"
    ],
    "record_identifier" => "bank-file.xml/line-1",
    "customer" => [
      "company_name" => "Jane's widgets",
      "email" => "jane@janeswidgets.fr"
    ],
    "bank_account" => [
      "account_holder_name" => "Jane Doe",
      "iban" => "FR14BARC20000055779911"
    ],
    "amendment" => [
      "original_mandate_reference" => "REFNMANDATE",
      "original_creditor_id" => "FR123OTHERBANK",
      "original_creditor_name" => "Existing DD Provider"
    ]
  ]
]);

MandateImportEntry mandateImportEntry = client.mandateImportEntries().create()
  .withCustomerCompanyName("Jane's widgets")
  .withCustomerEmail("jane@janeswidgets.fr")
  .withBankAccountAccountHolderName("Jane Doe")
  .withBankAccountIban("FR14BARC20000055779911")
  .withAmendmentOriginalMandateReference("REFNMANDATE")
  .withAmendmentOriginalCreditorId("FR123OTHERBANK")
  .withAmendmentOriginalCreditorName("Existing DD Provider")
  .withLinksMandateImport("IM000010790WX1")
  .execute();

mandateImportEntryCreateParams := gocardless.MandateImportEntryCreateParams{
  Customer: gocardless.MandateImportEntryCreateParamsCustomer{
    CompanyName: "Théâtre du Palais-Royal",
    Email:       "moliere@tdpr.fr",
  },
  BankAccount: gocardless.MandateImportEntryCreateParamsBankAccount{
    AccountHolderName: "Jean-Baptiste Poquelin",
    Iban:              "FR14BARC20000055779911",
  },
  Amendment: &gocardless.MandateImportEntryCreateParamsAmendment{
    OriginalMandateReference: "REFMANDATE",
    OriginalCreditorId:       "FR123OTHERBANK",
    OriginalCreditorName:     "Amphitryon",
  },
  Links: gocardless.MandateImportEntryCreateParamsLinks{
    MandateImport: "IM000010790WX1",
  },
}

mandateImportEntry, err := client.MandateImportEntries.Create(ctx, mandateImportEntryCreateParams)

var request = new GoCardless.Services.MandateImportEntryCreateRequest()
{
  Customer = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryCustomer()
  {
    CompanyName = "Jane's widgets",
    Email = "jane@janeswidgets.fr"
  },
  BankAccount = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryBankAccount()
  {
    AccountHolderName = "Jane Doe",
    Iban = "FR14BARC20000055779911"
  },
  Amendment = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryAmendment()
  {
    OriginalMandateReference = "REFNMANDATE",
    OriginalCreditorId = "FR123OTHERBANK",
    OriginalCreditorName = "Existing DD Provider"
  },
  Links = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryLinks()
  {
    MandateImport = "IM000010790WX1"
  }
};

var importResponse = await client.MandateImportEntries.CreateAsync(request);
GoCardless.Resources.MandateImportEntry entry = importResponse.MandateImportEntry;

Responsehttp

HTTP/1.1 201 Created
Content-Type: application/json
{
  "mandate_import_entries": {
    "record_identifier": "bank-file.xml/line-1",
    "created_at": "2018-03-03T00:00:00Z",
    "links": {
      "mandate_import": "IM000010790WX1"
    }
  }
}

Request Body

mandate_import_entriesobject

6 properties

linksobject

1 properties

mandate_importstring

Unique identifier, beginning with "IM".

record_identifierstring

A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.

mandateobject

3 properties

referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

authorisation_sourcestring

This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

webtelephonepaper

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

customerobject

16 properties

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

address_line1string

The first line of the customer's address. Required if mandate import scheme is either bacs or sepa.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code. Required if mandate import scheme is either bacs or sepa.

country_codestring

ISO 3166-1 alpha-2 code.

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

bank_accountobject

8 properties

account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

Bank account number - see local details for more information. Alternatively you can provide an iban.

bank_codestring

Bank code - see local details for more information. Alternatively you can provide an iban.

branch_codestring

Branch code - see local details for more information. Alternatively you can provide an iban.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

account_typestring

Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

amendmentobject

3 properties

original_mandate_referencestring

The unique SEPA reference for the mandate being amended. Required if mandate import scheme is sepa.

original_creditor_idstring

The creditor identifier of the direct debit originator. Required if mandate import scheme is sepa.

original_creditor_namestring

Data about the original mandate to be moved or modified.

Response 201

Resource created successfully

mandate_import_entriesobject

4 properties

record_identifierstring

A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

linksobject

Related resources

4 properties

mandate_importstring

The ID of the mandate import. This is returned when you create a Mandate Import.

mandateobject

customerobject

customer_bank_accountobject

processing_errorsobject

Per-resource processing errors

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

List all mandate import entries#

GET/mandate_import_entries

For an existing mandate import, this endpoint lists all of the entries attached.

After a mandate import has been submitted, you can use this endpoint to associate records in your system (using the record_identifier that you provided when creating the mandate import).

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/mandate_import_entries?mandate_import=IM000010790WX1 HTTP/1.1

@client.mandate_import_entries.all(
  params: {
    "mandate_import" => "IM000010790WX1"
  }
).each { |entry| puts entry.record_identifier }

for mandate_import_entry in client.mandate_import_entries.all(
  params= { "mandate_import": "IM000010790WX1" }
):
  print(mandate_import_entry.record_identifier)

const mandateImportEntries = await client.mandateImportEntries.list();

$client->mandateImportEntries()->all([
  "params" => ["mandate_import" => "IM000010790WX1"]
]);

for (MandateImportEntry entry : client.mandateImportEntries().all().withMandateImport("IM000010790WX1").execute()) {
  System.out.println(entry.getRecordIdentifier());
}

mandateImportEntryListParams := gocardless.MandateImportEntryListParams{
  MandateImport: "IM000010790WX1",
}

mandateImportEntryListPagingIterator := client.MandateImportEntries.All(ctx, mandateImportEntryListParams)
for mandateImportEntryListPagingIterator.Next() {
    mandateImportEntryListResult, err := mandateImportEntryListPagingIterator.Value(ctx)
    for _, mandateImportEntry := range mandateImportEntryListResult.MandateImportEntries {
        fmt.Println(mandateImportEntry.RecordIdentifier)
    }
}

var request = new GoCardless.Services.MandateImportEntryListRequest()
{
    MandateImport = "IM000010790WX1"
};

var response = client.MandateImportEntries.All(request);
foreach (GoCardless.Resources.MandateImportEntry entry in response)
{
    Console.WriteLine(entry.RecordIdentifier);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_import_entries": [
    {
      "record_identifier": "bank-file.xml/line-2",
      "created_at": "2018-03-03T00:00:01Z",
      "links": {
        "mandate_import": "IM000010790WX1"
      },
      "processing_errors": null
    },
    {
      "record_identifier": "bank-file.xml/line-1",
      "created_at": "2018-03-03T00:00:00Z",
      "links": {
        "mandate_import": "IM000010790WX1"
      },
      "processing_errors": {
        "mandate": ["Reference matches the start of the reference used by another mandate"]
      }
    }
  ],
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  }
}

Response 200

Successful response

mandate_import_entriesarray

4 properties

record_identifierstring

A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

linksobject

Related resources

4 properties

mandate_importstring

The ID of the mandate import. This is returned when you create a Mandate Import.

mandateobject

customerobject

customer_bank_accountobject

processing_errorsobject

Per-resource processing errors

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject