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.

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": "[email protected]"
    },
    "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: "[email protected]"
  },
  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": "[email protected]"
  },
  "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: "[email protected]"
  },
  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" => "[email protected]"
    ],
    "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("[email protected]")
  .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:       "[email protected]",
  },
  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 = "[email protected]"
  },
  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

linksobjectrequired

1 properties

mandate_importstringrequired

Unique identifier, beginning with "IM".

record_identifierstring | null

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 | null

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.

customerobjectrequired

16 properties

given_namestring | null

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

family_namestring | null

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

company_namestring | null

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 | null

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

languagestring | null

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 | null

The second line of the customer's address.

address_line3string | null

The third line of the customer's address.

citystring | null

The city of the customer's address.

regionstring | null

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 | null

ISO 3166-1 alpha-2 code.

phone_numberstring | null

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

swedish_identity_numberstring | null

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 | null

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_accountobjectrequired

8 properties

account_holder_namestringrequired

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 | null

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

bank_codestring | null

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

branch_codestring | null

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

country_codestring | null

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

ibanstring | null

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 | null

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_referencestringrequired

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

original_creditor_idstringrequired

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

original_creditor_namestringrequired

Data about the original mandate to be moved or modified.

Response 201

Resource created successfully

mandate_import_entriesobject

4 properties

record_identifierstring | null

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_importstringrequired

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

mandateobject

customerobject

customer_bank_accountobject

processing_errorsobject | null

Per-resource processing errors

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

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

Query Parameters

Name	Type	Description
`before`	string \| null	Cursor pointing to the end of the desired set.
`after`	string \| null	Cursor pointing to the start of the desired set.
`limit`	integer \| string	Number of records to return.
`mandate_import`	stringrequired
`status`	string

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 | null

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_importstringrequired

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

mandateobject

customerobject

customer_bank_accountobject

processing_errorsobject | null

Per-resource processing errors

metaobject

2 properties

limitintegerrequired

cursorsobjectrequired

2 properties

beforestring | nullrequired

Cursor pointing to the end of the desired set.

afterstring | nullrequired

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

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring