Setting up Mandates

Overview

Mandates are linked to customer profiles. Hence, it’s essential to understand the procedure for setting up a mandate, be it for an existing customer profile or a new one:

Creating a mandate: new customer

For new customer profiles, this process is completed in two stages. Firstly, create a ‘customer_id’ and register the necessary information under this customer profile. The provided example request outlines the minimum information necessary for the subsequent creation of a mandate:

{
  "reference": "customer_number_00001",
  "first_name": "Edward",
  "last_name": "Johnson",
  "billing": {
    "address": {
      "line_1": "152 Aldgate Drive",
      "city": "London",
      "country_code": "GB"
    },
    "email": "[email protected]"
  }
}

A successful request to the /customers endpoint will generate a customer record. You can then include the customer_id in the API Path URL when making a request to our /mandate endpoint to store the customer’s bank account details.

Creating a mandate: existing customer

For established customer profiles, ensure that the crucial information is already stored against the corresponding customer by submitting a GET request to the /customers/{customer_id} endpoint. If all the required parameters are present, you can submit a request to create a mandate.

If any of the required parameters are absent or incorrect, update the customer profile by submitting a PUT request to /customers/{customer_id}. Once the details are updated, submit a request to create a mandate.

Create a mandate

To create a mandate you are required to submit a request to the create a mandate endpoint containing the customer_id, a successful response will return a mandate_id.

POST /{customer_id}/mandates

{
  "mandate_type": "direct_debit",
  "sort_code": "123456",
  "account_number": "87654321",
  "account_name": "Mr E Johnson",
  "reference": "Custom Ref 001"
}

Response

A successful submission to the mandates API endpoint will generate a mandate with a unique ID, initially placed in a pending status.

The mandate will stay in the 'pending' status until its status is determined, transitioning to either 'active' or 'rejected'. A webhook will be dispatched to confirm the status update.

{
  "status": "pending",
  "mandate_id": "413516ad-2ba7-49f0-92a1-6900cc14f5ea"
}