GoCardlessDeveloper Docs
Create a sandbox account

Mandate

View as Markdown

Mandates represent the Direct Debit mandate with a customer.

GoCardless will notify you via a webhook whenever the status of a mandate changes.

Create a mandate#

POST/mandates

Creates a new mandate object.

POST https://api.gocardless.com/mandates HTTP/1.1
Content-Type: application/json
{
  "mandates": {
    "scheme": "bacs",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}
@client.mandates.create(
  params: {
    scheme: "bacs",
    links: {
      customer_bank_account: "BA123"
    }
  }
)
client.mandates.create(params={
  "scheme": "bacs",
  "metadata": {
    "contract": "ABCD1234"
   },
  "links": {
    "customer_bank_account": "BA123",
    "creditor": "CR123"
  }
})
const mandate = await client.mandates.create({
  scheme: "bacs",
  metadata: {
    contract: "ABCD1234"
   },
  links: {
    customer_bank_account: "BA123",
    creditor: "CR123"
  }
});
$client->mandates()->create([
  "params" => ["scheme" => "bacs",
               "metadata" => ["contract" => "ABCD1234"],
               "links" => ["customer_bank_account" => "BA123"]]
]);
Mandate mandate = client.mandates().create()
  .withScheme("bacs")
  .withLinksCustomerBankAccount("BA123")
  .withMetadata("contract", "ABCD1234")
  .execute();
mandateCreateParams := gocardless.MandateCreateParams{
  Scheme: "bacs",
  Links: gocardless.MandateCreateParamsLinks{
    CustomerBankAccount: "BA123",
    Creditor:            "CR123",
  },
  Metadata: map[string]string{"contract": "ABCD1234"},
}

mandate, err := client.Mandates.Create(ctx, mandateCreateParams)
var mandateRequest = new GoCardless.Services.MandateCreateRequest()
{
    Links = new GoCardless.Services.MandateCreateRequest.MandateLinks()
    {
        CustomerBankAccount = "BA0123"
    },
    Metadata = new Dictionary<string, string>()
    {
        {"internal_reference", "ref_09011991"}
    },
    Scheme = "bacs"
};

var mandateResponse = await client.Mandates.CreateAsync(mandateRequest);
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
Responsehttp
HTTP/1.1 201 Created
Location: /mandates/MD123
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
Request Body
mandatesobject
6 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.

schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

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
linksobject
2 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

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

Response 201

Resource created successfully

mandatesobject
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject

List mandates#

GET/mandates

Returns a cursor-paginated list of your mandates.

GET https://api.gocardless.com/mandates HTTP/1.1
@client.mandates.list

@client.mandates.list(params: { customer: "CU123" })

@client.mandates.list.records.each { |mandate| puts mandate.inspect }
client.mandates.list().records

client.mandates.list(params={"customer": "CU123"}).records
const mandates = await client.mandates.list();

// List all mandates associated with a given customer.
const customerMandates = await client.mandates.list({ customer: "CU123" });
$client->mandates()->list();

$client->mandates()->list([
  "params" => ["customer" => "CU123"]
]);
for (Mandate mandate : client.mandates().all().withCustomer("CU123").execute()) {
  System.out.println(mandate.getId());
}
mandateListParams := gocardless.MandateListParams{
  Customer: "CU123",
}

mandateListResult, err := client.Mandates.List(ctx, mandateListParams)
for _, mandate := range mandateListResult.Mandates {
    fmt.Println(mandate.Id)
}
var mandateRequest = new GoCardless.Services.MandateListRequest()
{
    Customer = "CU000123"
};

var mandateListResponse = client.Mandates.All(mandateRequest);
foreach (GoCardless.Resources.Mandate mandate in mandateListResponse)
{
    Console.WriteLine(mandate.Id);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "mandates": [{
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }]
}
Response 200

Successful response

mandatesarray
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single mandate#

GET/mandates/{mandate_id}

Retrieves the details of an existing mandate.

Path Parameters

NameTypeDescription
mandate_idrequiredstring

The mandate id

GET https://api.gocardless.com/mandates/MD123 HTTP/1.1
@client.mandates.get("MD123")
client.mandates.get("MD123")
const mandate = await client.mandates.find("MD123");
$client->mandates()->get("MD123");
Mandate mandate = client.mandates().get("MD123").execute();
mandate, err := client.Mandates.Get(ctx, "MD123")
var mandateResponse = await client.Mandates.GetAsync("MD0123");
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
Response 200

Successful response

mandatesobject
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject

Update a mandate#

PUT/mandates/{mandate_id}

Updates a mandate object. This accepts only the metadata parameter.

Path Parameters

NameTypeDescription
mandate_idrequiredstring

The mandate id

PUT https://api.gocardless.com/mandates/MD123 HTTP/1.1
Content-Type: application/json
{
  "mandates": {
    "metadata": {
      "key": "value"
    }
  }
}
@client.mandates.update(
  "MD123",
  params: {
    metadata: { contract_id: "ref_09011991" }
  }
)
client.mandates.update("MD123", params={
  "metadata": {"key": "value"}
})
const mandate = await client.mandates.update(
  "MD123",
  {
    metadata: {"key": "value"}
  }
);
$client->mandates()->update("MD123", [
  "params" => ["metadata" => ["key" => "value"]]
]);
client.mandates().update("MD123").withMetadata("contract_id", "ref_09011991").execute();
mandateUpdateParams := gocardless.MandateUpdateParams{
  Metadata: map[string]string{"key": "value"},
}

mandate, err := client.Mandates.Update(ctx, "MD123", mandateUpdateParams)
var mandateRequest = new GoCardless.Services.MandateUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"internal_reference", "ref_09011991"}
    }
};

var mandateResponse = await client.Mandates.UpdateAsync("MD0123", mandateRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "pending_submission",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "key": "value"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
Request Body
mandatesobject
1 properties
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.

Response 200

Successful response

mandatesobject
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject

Cancel a mandate#

POST/mandates/{mandate_id}/actions/cancel

Immediately cancels a mandate and all associated cancellable payments. Any metadata supplied to this endpoint will be stored on the mandate cancellation event it causes.

This will fail with a cancellation_failed error if the mandate is already cancelled.

Path Parameters

NameTypeDescription
mandate_idrequiredstring

The mandate id

POST https://api.gocardless.com/mandates/MD123/actions/cancel HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {}
  }
}
@client.mandates.cancel("MD123")
client.mandates.cancel("MD123")
const mandateResponse = await client.mandates.cancel("MD123");
$client->mandates()->cancel("MD123");
client.mandates().cancel("MD123").execute();
mandateCancelParams := gocardless.MandateCancelParams{}
mandate, err := client.Mandates.Cancel(ctx, "MD123", mandateCancelParams)
var mandateResponse = await client.Mandates.CancelAsync("MD0123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "cancelled",
    "scheme": "bacs",
    "next_possible_charge_date": null,
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
Request Body
mandatesobject
1 properties
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.

Response 200

Action completed successfully

mandatesobject
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject

Reinstate a mandate#

POST/mandates/{mandate_id}/actions/reinstate

Reinstates a cancelled or expired mandate to the banks. You will receive a resubmission_requested webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a submitted webhook, followed by a reinstated or failed webhook up to two working days later. Any metadata supplied to this endpoint will be stored on the resubmission_requested event it causes.

This will fail with a mandate_not_inactive error if the mandate is already being submitted, or is active.

Mandates can be resubmitted up to 10 times.

Path Parameters

NameTypeDescription
mandate_idrequiredstring

The mandate id

POST https://api.gocardless.com/mandates/MD123/actions/reinstate HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {
      "ticket_id": "TK123"
    }
  }
}
@client.mandates.reinstate("MD123")
client.mandates.reinstate("MD123")
const mandateResponse = await client.mandates.reinstate("MD123");
$client->mandates()->reinstate("MD123");
client.mandates().reinstate("MD123").execute();
mandateReinstateParams := gocardless.MandateReinstateParams{}
mandate, err := client.Mandates.Reinstate(ctx, "MD123", mandateReinstateParams)
var mandateResponse = await client.Mandates.ReinstateAsync("MD0123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandates": {
    "id": "MD123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "reference": "REF-123",
    "status": "submitted",
    "scheme": "bacs",
    "next_possible_charge_date": "2014-11-10",
    "metadata": {
      "contract": "ABCD1234"
    },
    "links": {
      "customer_bank_account": "BA123",
      "creditor": "CR123",
      "customer": "CU123"
    }
  }
}
Request Body
mandatesobject
1 properties
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.

Response 200

Action completed successfully

mandatesobject
16 properties
idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

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.

statusstring

One of:

  • pending_customer_approval: the mandate has not yet been signed by the second customer
  • pending_submission: the mandate has not yet been submitted to the customer's bank
  • submitted: the mandate has been submitted to the customer's bank but has not been processed yet
  • active: the mandate has been successfully set up by the customer's bank
  • suspended_by_payer: the mandate has been suspended by payer
  • failed: the mandate could not be created
  • cancelled: the mandate has been cancelled
  • expired: the mandate has expired due to dormancy
  • consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
  • blocked: the mandate has been blocked and payments cannot be created
pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer
schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping
next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject
4 properties
customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties
max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible
max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

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
funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

  • managed will be moved through GoCardless' account, batched, and payed out.
  • direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.
manageddirect
consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic
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
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard