Variable recurring payments

Learn how to accept recurring payments with the Payments API v3.

Variable Recurring Payments (VRP) enable you to receive payments from customers on a recurring basis.

The first step of a VRP is a mandate. A mandate is a set of constraints that determine:

  • The period over which payments can be made.
  • The maximum amount of an individual payment.
  • The maximum amount that can be paid over a specified period.

After your user authorises a mandate, you can accept payments for a variety of purposes such as fixed or variable subscriptions, or ad hoc background payments.

Types of VRP

VRPs belong to one of two categories: sweeping VRPs or commercial VRPs.

Sweeping VRPs are payments between a customers account, as defined by the CMA. For example, moving money between current accounts, paying off credit card debt, or moving money to savings.

Commercial VRPs are payments that don't fall within the scope of sweeping as defined by the CMA. This includes applications such as e-commerce payments, subscriptions to a variable service, or investments.

When you create a mandate, you provide a scope to specify whether it is for commercial or sweeping payments.

VRP mandate and payment journey

To set up recurring payments, your user must first authorise a payment mandate. This mandate represents the authorisation that a user has given you to take payments from their payment account.

At a high level, the steps required to progress a user to making a payment are as follows:

  1. Define the mandate and consent parameters, and set up the mandate to be authorised.
    This is done through a mandate creation request.
  2. Send your user through a UI to authorise the mandate.
    You can use a TrueLayer UI such as the HPP, or build your own.
  3. Create a payment that uses the authorised mandate's id as the payment_method.
  4. Receive status updates on the payment attempt, and receive funds.
    This is automatic with a TrueLayer merchant account, or you can use references for external accounts.

Testing in Sandbox

Clients are encouraged to start exploring and testing our API in the Sandbox environment. The behaviour of our Sandbox API is identical to the Live environment, except for the actual flow of funds. This means that you will not be able to see end to end references in action. Click here for more information about references.

In this environment you'll find the NatWest Sandbox provider (ob-natwest-vrp-sandbox). To authorise a mandate on the NatWest sandbox authentication page, you can use the following details:

  • Customer number: 123456789012
  • Pin / password: 5 7 2 / 4 3 6.

If you want to test providing the optional remitter object, remember that it has to be one of the two accounts that are selectable during the authorisation flow for the provided NatWest Sandbox account. This means the sort code and account numbers should be either 500000 and 12345601 OR 500000 and 12345602. That account is then shown on the NatWest page after authorisation. If you don't provide valid account identifiers (sort code and account number), mandate creation fails.