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.

Obtain a client_credentials access token

Recurring payment mandates require the caller to have either the recurring_payments:sweeping or recurring_payments:commercial OAuth2 scope.

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

📘

payments scope

In order to use the mandate to create a payment, you will also need a payments scope.
We recommend you create a separate token with that scope when you need it.

Build a mandate creation request

To create a mandate, you need to specify the beneficiary and constraints of the mandate.

• Beneficiary: The beneficiary of a mandate can either be a merchant account or an external account. The request body schema is slightly different based on which one you choose to use. See our API reference to find out what information you need to send in each scenario.

• Constraints: The constraints of a mandate define the time interval in which the mandate is valid. They also define the maximum amount of money that can be moved using a single payment, as well as the periodic limits which define the maximum amount of money that can be moved using the mandate during a variable period of time.

🚧

The details of a mandate cannot be changed after the mandate is created. For this reason, you need to make sure the mandate's beneficiary as well as constraints are correct at the time of creation.

You can then start building the mandate creation request. From your server, make a POST request to /v3/mandates, and include the following values:

Parameter name	Required	Description
mandate		The agreement between a merchant and their user enabling the merchant to take payments from the user's payment account. Check out the API reference for more details on the object.
currency		The code of the currency that the payment will be made in. Available values: GBP, EUR
user		Details of the user who is making the payment. Whether or not these fields are required depends on the regulatory status of the client initiating the payment. Check out the API reference for more details on the object.
constraints		Sets the limits for the payments that can be created by the mandate. If a payment is attempted that doesn't fit within these constraints it will fail.

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, you will get back 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 the 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 following:

• Error types: Check out the error codes and relevant actions to take, 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.
2. Ask the user to authorise the mandate.
3. Optionally, delete the existing mandate.