Mandate Import

Mandate Imports allow you to migrate existing mandates from other providers into the GoCardless platform.

The process is as follows:

Create a mandate import
Add entries to the import
Submit the import
Wait until a member of the GoCardless team approves the import, at which point the mandates will be created
Link up the mandates in your system

When you add entries to your mandate import, they are not turned into actual mandates until the mandate import is submitted by you via the API, and then processed by a member of the GoCardless team. When that happens, a mandate will be created for each entry in the import.

We will issue a mandate_created webhook for each entry, which will be the same as the webhooks triggered when creating a mandate using the mandates API. Once these webhooks start arriving, any reconciliation can now be accomplished by checking the current status of the mandate import and linking up the mandates to your system.

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

Create a new mandate import#

POST/mandate_imports

Mandate imports are first created, before mandates are added one-at-a-time, so this endpoint merely signals the start of the import process. Once you've finished adding entries to an import, you should submit it.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/mandate_imports HTTP/1.1
Content-Type: application/json
{
  "mandate_imports": {
    "scheme": "bacs"
  }
}

@client.mandate_imports.create(params: {
  scheme: "bacs"
})

client.mandate_imports.create(params={
  "scheme": "bacs"
})

const mandateImport = await client.mandateImports.create({
  scheme: "bacs"
});

$client->mandateImports()->create([
  "params" => ["scheme" => "bacs"]
]);

MandateImport mandateImport = client.mandateImports().create()
  .withScheme(com.gocardless.services.MandateImportService.MandateImportCreateRequest.Scheme.BACS)
  .execute();

mandateImportCreateParams := gocardless.MandateImportCreateParams{
  Scheme: "bacs",
}

mandateImport, err := client.MandateImports.Create(ctx, mandateImportCreateParams)

var importRequest = new GoCardless.Services.MandateImportCreateRequest()
{
    Scheme = GoCardless.Services.MandateImportCreateRequest.MandateImportScheme.Bacs
};

var importResponse = await client.MandateImports.CreateAsync(importRequest);
GoCardless.Resources.MandateImport mandateImport = importResponse.MandateImport;

Responsehttp

HTTP/1.1 201 Created
Location: /mandate_imports/IM123
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM123",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Request Body

mandate_importsobject

2 properties

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

linksobject

Related resources

1 properties

creditorstring

ID of the associated creditor. Only required if your account manages multiple creditors.

Response 201

Resource created successfully

mandate_importsobject

5 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the mandate import.

created: A new mandate import.
submitted: After the integrator has finished adding mandates and submitted the import.
cancelled: If the integrator cancelled the mandate import.
processing: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported.
processed: When all mandates have been imported successfully.

createdsubmittedcancelledprocessingprocessed

schemestring

The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

linksobject

Related resources

1 properties

creditorstring

ID of the associated creditor.

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

Get a mandate import#

GET/mandate_imports/{mandate_import_id}

Returns a single mandate import.

Path Parameters

Name	Type	Description
`mandate_import_id`required	string	The mandate import id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/mandate_imports/IM123 HTTP/1.1

@client.mandate_imports.get("IM123")

client.mandate_imports.get("IM123")

const mandateImport = await client.mandateImports.find("IM123");

$client->mandateImports()->get("IM123");

MandateImport mandateImport = client.mandateImports().get("IM123").execute();

mandateImport, err := client.MandateImports.Get(ctx, "IM123", gocardless.MandateImportGetParams{})

var response = await client.MandateImports.GetAsync("IM123");
GoCardless.Resources.MandateImport mandateImport = response.MandateImport;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM123",
    "scheme": "bacs",
    "status": "created",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Response 200

Successful response

mandate_importsobject

5 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the mandate import.

created: A new mandate import.
submitted: After the integrator has finished adding mandates and submitted the import.
cancelled: If the integrator cancelled the mandate import.
processing: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported.
processed: When all mandates have been imported successfully.

createdsubmittedcancelledprocessingprocessed

schemestring

The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

linksobject

Related resources

1 properties

creditorstring

ID of the associated creditor.

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

Submit a mandate import#

POST/mandate_imports/{mandate_import_id}/actions/submit

Submits the mandate import, which allows it to be processed by a member of the GoCardless team. Once the import has been submitted, it can no longer have entries added to it.

In our sandbox environment, to aid development, we automatically process mandate imports approximately 10 seconds after they are submitted. This will allow you to test both the "submitted" response and wait for the webhook to confirm the processing has begun.

Path Parameters

Name	Type	Description
`mandate_import_id`required	string	The mandate import id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/mandate_imports/IM123/actions/submit HTTP/1.1

@client.mandate_imports.submit("IM123")

client.mandate_imports.submit("IM123")

const mandateImport = await client.mandateImports.submit("IM123");

$client->mandateImports()->submit("IM123");

client.mandateImports().submit("IM123").execute();

mandateImportSubmitParams := gocardless.MandateImportSubmitParams{}
mandateImport, err := client.MandateImports.Submit(ctx, "IM123", mandateImportSubmitParams)

var response = await client.MandateImports.SubmitAsync("IM123");
GoCardless.Resources.MandateImport mandateImport = response.MandateImport;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM123",
    "scheme": "bacs",
    "status": "submitted",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

POST https://api-sandbox.gocardless.com/mandate_imports/IM123/actions/submit HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM123",
    "scheme": "bacs",
    "status": "processing",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Request Body

mandate_importsobject

Response 200

Action completed successfully

mandate_importsobject

5 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the mandate import.

created: A new mandate import.
submitted: After the integrator has finished adding mandates and submitted the import.
cancelled: If the integrator cancelled the mandate import.
processing: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported.
processed: When all mandates have been imported successfully.

createdsubmittedcancelledprocessingprocessed

schemestring

The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

linksobject

Related resources

1 properties

creditorstring

ID of the associated creditor.

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

Cancel a mandate import#

POST/mandate_imports/{mandate_import_id}/actions/cancel

Cancels the mandate import, which aborts the import process and stops the mandates being set up in GoCardless. Once the import has been cancelled, it can no longer have entries added to it. Mandate imports which have already been submitted or processed cannot be cancelled.

Path Parameters

Name	Type	Description
`mandate_import_id`required	string	The mandate import id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/mandate_imports/IM123/actions/cancel HTTP/1.1

@client.mandate_imports.cancel("IM123")

client.mandate_imports.cancel("IM123")

const mandateImportResponse = await client.mandateImports.cancel("IM123");

$client->mandateImports()->cancel("IM123");

client.mandateImports().cancel("IM123").execute();

mandateImportCancelParams := gocardless.MandateImportCancelParams{}
mandateImport, err := client.MandateImports.Cancel(ctx, "IM123", mandateImportCancelParams)

var response = await client.MandateImports.CancelAsync("IM123");
GoCardless.Resources.MandateImport mandateImport = response.MandateImport;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_imports": {
    "id": "IM123",
    "scheme": "bacs",
    "status": "cancelled",
    "created_at": "2018-03-12T14:03:04.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}

Request Body

mandate_importsobject

Response 200

Action completed successfully

mandate_importsobject

5 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the mandate import.

created: A new mandate import.
submitted: After the integrator has finished adding mandates and submitted the import.
cancelled: If the integrator cancelled the mandate import.
processing: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported.
processed: When all mandates have been imported successfully.

createdsubmittedcancelledprocessingprocessed

schemestring

The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

linksobject

Related resources

1 properties

creditorstring

ID of the associated creditor.

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