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:

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}
Host: api.truelayer-sandbox.com
{
		"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:

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.