Account icon

Manage mandates for direct debits in the UK

Learn about the API requests for managing mandates for direct debits in the UK.

Limited availability
Direct debits in the UK are in pilot phase. Some of the processes and documentation may change as the feature evolves.

A mandate is an authorization that your user gives for allowing a counterparty to debit funds from the user's business account. When your user authorizes a one-time or recurring direct debit, the counterparty's bank notifies Adyen, and a mandate is created.

After a mandate is created, you can view, amend, or cancel the mandate using Adyen's APIs. This page explains how to make API requests related to mandates and how to get updates about the result of these requests.

Requirements

Before you begin, make sure that you fulfill the following requirements:

Requirement Description
Integration type You must have an Adyen for Platforms integration that includes business accounts.
API credential roles Make sure that your web service API key has the following role:
  • Manage Direct Debit Mandates role
Capabilities Make sure that you enabled the following capability for your user:
  • sendToThirdParty
Webhooks In your Customer Area, subscribe to the following webhook:
  • Mandate Webhooks
Limitations Currently, these endpoints only support mandates created for accounts in the UK.
Setup steps Reach out to your Adyen contact to enable direct debits in the UK.

View a list of mandates

You can view a list of all mandates created for a business account, regardless of the status.

To get this list:

  1. Make a GET /mandates request, specifying at least one of following parameters:

    Parameter name Parameter type Required Description
    balanceAccountId Query The unique identifier of the balance account linked to your user's business account.
    paymentInstrumentId Query The unique identifier of your user's business account.

    The following code example shows a GET /mandates request for a balance account with ID BA000000000000000000000001, linked to a business account with ID PI000000000000000000000001.

    A successful request returns an HTTP 200 response.

  2. In the HTTP 200 response, verify that you received the following parameters:

    Response parameter Description
    mandates An array that contains all mandates that match the query parameters.
    link An object that contains links to the next or previous page, when applicable.

View a specific mandate

To view the details of a specific mandate:

  1. Make a GET /mandates/{mandateId} request, specifying the mandateId in the path.

    The following example shows how to get the details of a mandate with ID MNDT000000000000000000000001.

    A successful request returns an HTTP 200 response.

  2. In the HTTP 200 response, verify that you received an object with the following parameters:

    Response parameter Description
    balanceAccountId The unique identifier of the balance account to which the mandate applies.
    counterparty An object that contains information about the party that receives the funds from the direct debit.
    createdAt The date when the mandate was created.
    id The unique identifier of the mandate.
    paymentInstrumentId The unique identifier of your user's business account.
    status The current status of the mandate. Possible values: pending, approved, or cancelled.
    type The type of mandate. Possible value: bacs.
    updatedAt The date when the mandate was updated, if applicable.

Amend a mandate

You can amend a mandate to change what business account the mandate applies to. For example, consider a user that opens a second business account in your platform, exclusively to handle monthly expenses. Instead of creating a new mandate, your user can amend the ID of the business account.

To amend a mandate:

  1. Make a PATCH /mandates/{mandateId} request, specifying the following parameters:

    Parameter name Parameter type Required Description
    mandateId Path -white_check_mark- The unique identifier of the mandate.
    paymentInstrumentId Request -white_check_mark- The unique identifier of your user's business account.

    The following example shows how to make a PATCH /mandates/{mandateId} request for updating the payment instrument ID to which the mandate corresponds.

  2. Verify that you receive an HTTP 202 — Accepted response with no content. This means that the request was correct.
    After this, Adyen processes the request asynchronously.

  3. To be informed about the result of the request, listen to the webhooks that Adyen sends to your server.

Cancel a mandate

To cancel an existing mandate:

  1. Make a POST /mandates/{mandateId}/cancel request, specifying the mandateId in the path.

    The following example shows how to cancel a mandate with ID MNDT000000000000000000000001.

  2. Verify that you receive an HTTP 202 — Accepted response with no content. This means that the request was correct.
    After this, Adyen processes the request asynchronously.

  3. To be informed about the result of the request, listen to the webhooks that Adyen sends to your server.

Get updates about requests

Adyen sends webhooks to your server to inform you when a mandate is created, updated, or canceled. Using these webhooks, you can track information such as:

  • The date of creation
  • The current status
  • The date of update, if applicable

The following tabs show examples of the webhooks that Adyen sends.

See also