Create a payment mandate

Use the following steps to learn how to create a new payment mandate for your user. You'll need this mandate to set up recurring payments.

To create a payment mandate, you need to:

1. Authenticate your request properly, which requires:
   1. An access_token with the correct scopes, included as a bearer header with your request.
   2. You to sign your requests with a valid Tl-Signature header.
   3. An Idempotency-Key header so you can retry your requests.
2. Make a POST mandate creation request, including the right beneficiary and constraints for the mandate.

1. Generate an access_token and authenticate your request

A VRP mandate needs an access_token that you've created with either the recurring_payments:sweeping or recurring_payments:commercial scope. The purpose of these two scopes are:

• recurring_payments:sweeping: The sweeping use case for open banking variable recurring payments, where users can move funds between two accounts in their name.
• recurring_payments:commercial: The commercial use case for open banking variable recurring payments. This permission needs certain agreements to be in place and can allow some uses of VRP that aren't defined in the VRP specification.

To generate an access_token with one of these scopes, make a POST request to the /token/connection endpoint.

curl -X POST
    -d grant_type=client_credentials
    -d client_id=${client_id}
    -d client_secret=${client_secret}
    -d scope=payments recurring_payments:sweeping
    https://auth.truelayer-sandbox.com/connect/token

curl -X POST
    -d grant_type=client_credentials
    -d client_id=${client_id}
    -d client_secret=${client_secret}
    -d scope=payments recurring_payments:commercial
    https://auth.truelayer-sandbox.com/connect/token

The access_token you receive in response to your request is used as a bearer header when you make a mandate creation request.

You must also sign your request with a Tl-Signature header and include an Idempotency-Key header with your request.

Any payments you create on the mandate need the payments scope as well as the sweeping or commercial scopes.

2. Mandate creation request

To create a mandate, make a POST request to the /v3/mandates endpoint, providing values for the parameters below.

These are the available parameters in a request to create a payment on a mandate:

📘

After creating a mandate, you cannot update or change it. To change the constraints (for example, the maximum possible value of a single payment), you need to create a new mandate. You can revoke mandates you no longer need to use.

From the parameters above, there are a few that require more consideration than others. These are provider selection, the beneficiary, and some of the constraints of the mandate.

Provider selection in mandates

There are two types of provider selection you can choose at mandate creation: user_selected and preselected. To choose one, provide it as a value for the mandate.provider_selection.type parameter.

For user selected mandates, the user can choose the banking provider that the mandate sets up payments from. The list of providers they can choose from depends on the values you provide for the mandate.provider_selection.filter object. The filter object works the same way as it does for single payments.

For preselected mandates, you need to provide the provider_id for the banking provider the user wants to pay from. Optionally, you can provide the user's bank details as part of the mandate.provider_selection.remitter object to simplify the flow further.

Beneficiaries in mandates

There are two types of beneficiary you can choose at mandate creation: merchant_account and external_account. To choose one, provide it as a value for the mandate.beneficiary.type parameter.

If you choose a merchant account as the beneficiary, you need to provide the associated merchant_account_id.

If you choose an external account as the beneficiary, you need to provide the name associated with the beneficiary account, and then provide the applicable sort code and account number or IBAN. These are provided as part of the mandate.beneficiary.account_holder_name and mandate.beneficiary.account_identifier parameters respectively.

The periodic limits constraint in mandates

Periodic limits are one of several constraints you can define for a mandate, in addition to a start date, end date, and maximum value of an individual payment. Periodic limits enable to you specify a maximum amount that can be paid through a mandate over a specific time period.

There are six optional child objects for the constraints.periodic_limits parameter:

• day
• week
• fortnight
• month
• half_year
• year

For each of these objects, there are two child parameters you can set, which affect their behaviour:

• maximum_amount: This is the maximum amount that can be paid over the mandate for the parent time period, such as day or week. This must be greater than or equal to constraints.maximum_individual_amount.
• period_alignment: When the parent time period, such as day or week, applies from. There are two possible values: consent or calendar:
  • A value of consent means the maximum amount that can be paid over the parent time period starts from the point the user consents to the mandate.
  • A value of calendar means the maximum amount that can be paid over the parent time period is always based on calendar dates. If the user consents midway through a period, the maximum_amount is prorated to the end of the time period. For example, if a user agrees a maximun of 5,000 per month and consents halfway through the month, for the remainder of that first month, they can pay a maximum of 2,500 over the mandate.

You can specify a maximum_amount for several different time periods, and they all apply.

🚧

The UK bank Monzo does not support the day, week, fortnight, and half_year periodic limit objects. They also do not support the calendar method for period_alignment.

Mandate creation request and response examples

This is an example of a mandate creation request:

curl --request POST \
     --url https://api.truelayer.com/v3/mandates \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: $(uuidgen)" \
     --header "Tl-Signature: TestRequest..Signature" \
     --header "Authorization: Bearer $AUTH_TOKEN" \
     --data '{
  "mandate": {
    "type": "sweeping",
    "provider_selection": {
       "filter": {
          "countries": ["GB"],
          "release_channel": "private_beta"
       },
       "type": "user_selected"
    },
    "beneficiary": {
       "type": "external_account",
       "account_holder_name": "My Bank Account",
       "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "111111",
          "account_number": "10001000"
       }
    }
  },
  "currency": "GBP",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
    "name": "Remi Terr",
    "email": "[email protected]",
    "phone": "+44777777777"
  },
  "constraints": {
    "valid_from": "2022-05-10T00:00:00.000Z",
    "valid_to": "2022-05-11T00:00:00.000Z",
    "maximum_individual_amount": 100,
    "periodic_limits": {
      "week": {
        "maximum_amount": 1000,
        "period_alignment": "calendar"
      }
    }
  }
}'

If the mandate creation request is successful, the response contains the id of the mandate, the id of the user on the mandate and the resource_token.

{
  "id": "string",
  "user": {
    "id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941"
  },
  "resource_token": "string"
}

The resource_token is a token you need to use in the subsequent calls made to authorise the newly created mandate. This token is short-lived (15 minutes) and it can be safely shared with a frontend channel.

Error handling

In case you encounter errors in your integration, refer to the payments API errors page to check error codes and the appropriate actions to modify your request.

Update mandate details

If you need your user to change or update any mandate details in the future:

1. Create a new mandate with the new details needed.
   Optionally, you can revoke the old mandate .
2. Have your user authorise the new mandate.