Overview

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.

Payment mandates belong to one of three types:

• Sweeping VRPs - For moving money between your user's own accounts (’me-to-me’)
• Wave 1 VRPs - For recurring payments from your user to an organisation, within specific use cases (utilities, government payments, financial services, charity)
• Direct Debits - For Direct Debits.

Wave 1 bank on file

To create a wave 1 mandate, you need to pass additional parameters when dealing with wave 1 use cases, but you do not need to include any additional scopes besides payments.

When you configure a mandate, you need to

Wave 1 bank on file payments are approved for four specific use cases:

Contact us if you are unsure whether your intended use case falls within one of these categories.

1. Generate an access_token and authenticate your request

A VRP mandate needs an access_token that you've created with a payments scope, alongside recurring_payments:sweeping if you are authenticating a sweeping VRP mandate. Wave 1 VRP mandates only need payments.

Wave 1 bank on file parameters

These parameters are required when creating a wave 1 bank on file mandate only.

You must specify a use_case inside the mandate object.

When you create a payment on a wave 1 VRP mandate, you must also state whether the user is present for the payment using the user_interaction field inside the payment_method. Do this using the present or not_present values.

2. Create a mandate

To create a mandate, make a POST request to the /v3/mandates endpoint. All mandate requests must include the following parameters:

• mandate.type - must be either sweeping, commercial, or direct_debit . For wave 1 bank on file payments, choose commercial.
• mandate.provider_selection.type - either user_selected or preselected
• mandate.beneficiary.type - the type of account that the money will be moving to. Can be either merchant_account or external_account
• currency - either GBP or EUR
• constraints - Sets limits for payments (max individual amount, periodic limits, valid dates)
• mandate.use_case - Required when vrp_wave is wave_1. Must be one of:
  • utilities
  • government_payments
  • financial_services
  • charity

This example shows a Wave 1 commercial VRP mandate that would be used for utility bill payments:

curl --request POST \
  --url https://api.truelayer-sandbox.com/v3/mandates \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UUID>' \
  --header 'Tl-Signature: <SIGNATURE>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data '{
  "mandate": {
    "type": "commercial",
    "use_case": "utilities",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": ["GB"],
        "release_channel": "general_availability"
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "<YOUR_MERCHANT_ACCOUNT_ID>",
      "account_holder_name": "Energy Company Ltd"
    }
  },
  "currency": "GBP",
  "user": {
    "id": "<USER_ID>",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+441234567890"
  },
  "constraints": {
    "valid_from": "2026-03-31T00:00:00.000Z",
    "valid_to": "2027-03-31T00:00:00.000Z",
    "maximum_individual_amount": 50000,
    "periodic_limits": {
      "month": {
        "maximum_amount": 150000,
        "period_alignment": "calendar"
      }
    }
  }
}'

Examples of payments where the user is not_present include utility bill payments which get taken automatically out of a user’s account.

Examples of payments where the user is present include ‘topping up’ a utility bill account, where the user chooses to pay a specific amount within the constraints of a mandate which has already been set up.

Next steps

After creating your mandate, you'll need to:

1. Authorize the mandate - Guide your user through the bank authorization flow for recurring payments
2. Create payments on the mandate - Make recurring payments using the authorized mandate
3. Monitor mandate status - Track active, expired, and revoked mandates