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",
      "postcode": "E1 7RT",
      "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 /mandates

{
  "customer_id": "0190c0a2-2c97-72a8-83d5-928b91fc45b3",
  "mandate_type": "direct_debit",
  "sort_code": "123456",
  "account_number": "87654321",
  "account_name": "Mr E Johnson",
  "reference": "Custom Ref 001"
}

Please note that in our QA environment, the account number and sort code are validated. To avoid errors during testing, ensure that these details are both valid and correctly linked.

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"
}