Create a payment on a mandate

Learn how to create a payment on a mandate.

After you have created a payment mandate, and your user has authorised it, you can create a payment on the mandate. Once you create the payment, you can track and monitor it in the same way as a non-recurring payment.

As your user has authorised a mandate, the flow for a payment on a mandate differs from a non-recurring payment. After payment creation, there's no authorisation required, so it executes immediately.

1. Authenticate a payment on a mandate

To create a payment on a mandate, you must authenticate your request. This ensures only you can create payments on the mandate. Authentication requires you to:

  • Generate an access_token with the paymentsscope. It must also have either the recurring_payments:sweeping or recurring_payments:commercial scope as appropriate.
    You include the access_token as a bearer header with your request.
  • Generate public and private keys and set up request signing, so you can include a Tl-Signature header with your requests.

Your request should also include an idempotency key, which you provide as a Idempotency-Key header. This ensures that you can safely retry requests without creating duplicate payments.

2. Configure a payment on a mandate

To create a payment on a VRP mandate, you must make a POST request to the /v3/payments endpoint. For a payment on a mandate, the request must use mandate as the value for the payment_method.type parameter.

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

amount_in_minorThe amount in minor units.

Minor units are the smallest units of a currency, depending on the number of decimals. For example: 1 GBP = 100 pence.
currencyThe currency of the payment as an ISO 4217 code. TrueLayer supports GBP and EUR.

You cannot make a payment from GBP currency to a EUR account, specified in the payment_method.beneficiary.account_identifier object.
payment_method.typeThe payment method for the payment.

For a payment on a mandate, use mandate.

For a single payments , use bank_transfer as the type.
payment_method.mandate_idThe id of the mandate used to authorise the payment.
payment_method.referenceThe reference for the payment that displays on the remitter's bank statement.

Reference to be used on the payment as EndToEndIdentification.Read more about payment references here.

Some providers have character limits for this field. We recommend making your reference as short as possible, ideally under 18 characters.
payment_method.retry.typeIf you have contacted us to enable retries, use this parameter to enable smart retry on failure by specifying retry type. Values: standard, smart
payment_method.retry.forSpecify how long to retry the payment for if it fails. Refer to the API Reference for the details of the format and supported range
retry.ensure_minimum_balance_in_minorOptionally, specify a remaining balance threshold after taking this payment. (Only applies when retry.type is smart)
userSome personal information about the user remitting funds, and an ID.

For a payment on a mandate, it's mandatory to include the payer's full name and one of their email address or phone number.

You can use a user ID from a previous Payments API v3 request to represent a user who has previously made a payment or created a mandate.

Some providers have upper limits for this field. If you need to shorten a name to fit these limits, we recommend removing middle names first, then initialising the first name. For example:

Jonathan Alexander Doe > Jonathan Doe > J Doe

Learn more about the user information to include in your payment requests.
metadataAn optional field to add custom data to a payment. This is saved on payment creation and returned on every payment retrieve.
related_productsEnables you to enable a related product for a payment. Currently, you can only enable SignUp+ by including an empty signup_plus object.
authorization_flowEnables you to start the authorisation flow as part of a direct API integration, where you build your own UI.

However, this doesn't apply to payments on a mandate, as they don't need authorisation.

Payment request and response examples

Payment on a mandate request example

This is an example of a request to create a payment on a mandate in the sandbox environment.

POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: {Random UUID}
Tl-Signature: {Signature}
Authorization: Bearer {Access_token}
		"payment_method": {
				"type": "mandate",
		"mandate_id": "d636337e-89e3-4d29-8ccb-da34f2c2e98c"
		"amount_in_minor": 1,
		"reference": "reference123",
		"currency": "GBP",
    "user": {
        "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
        "name": "Jonathan Sandbridge",
        "email": "[email protected]",
        "phone": "+447809123456",
        "date_of_birth": "1992-11-28",
        "address": {
            "address_line1": "40 Finsbury Square",
            "city": "London",
            "state": "London",
            "zip": "EC2a 1PX",
            "country_code": "GB"

You can test the authorisation flow your user would see in a mock bank in the sandbox environment.

Payment on a mandate response example

If the payment request is successful, you receive a response that contains the following fields:

idThe ID for the created payment.
user.idAn ID for the remitter.

An ID is generated automatically if you leave the user id blank when you create the payment.

If you use the same id as a previous payment, both payments will be associated with the ID.

You can use the /v3/mandates endpoint to return a list of mandates authorised by a given
resource_tokenA token that lasts for 15 minutes from payment creation. You be use to view the settlement status of the payment.

This code block contains an example of the response when you create a payment on a mandate.

  "id": "string",
  "user": {
    "id": "{UUID}"
  "resource_token": "a-secret-token"

A newly-created payment on a mandate has the status authorizing and moves through the same series of statuses that that a single payment does .

Unlike a single payment however, VRPs don't need to be authorised by the end user (as long as the mandate has already been authorised). You don't need to do anything else for the payment to move to a terminal status.

You receive a payment webhook that tells you the outcome of the payment.

[Optional] Enable retries for failed payments


Retry is an opt-in feature

This feature is optional, and is disabled by default. Contact us if you would like to enable this feature

This optional feature enables you to automatically retry failed payments to improve conversion. To use retries in your payments on a mandate, ensure you contact us to enable it, and then provide information for the following parameters in your payment request:

  • payment_method.retry.type: The type of retry logic to apply for the payment. Can be standard or smart, explained below.
  • payment_method.retry.for: How long to retry the payment for. Has a minimum duration of 30 minutes and a maximum of 6 hours. You should specify this in this format: 30m, 12h, 7d.
  • payment_method.retry.ensure_minimum_balance_in_minor: Only available for smart retries. This checks the effective balance in the remitter's account will exceed a certain amount after the payment.

Types of retry

Standard Retry

The payment on a mandate is retried if the banking provider is unavailable, or there's an error with the provider.

Smart Retry

All error types are retried, including but not limited to:

  • Insufficient funds
  • Constraint violation
  • Provider error
  • User cancellation
  • Expired payment
  • Revoked mandate
  • Invalid details
  • General connectivity issues

Optionally, for smart retries, you can specify the retry.ensure_minimum_balance_in_minor parameter. This ensures the specified balance remains in the payment account after the transfer is complete.