Variable recurring payments integration

There are two steps to integrating Signup+ with the variable recurring payments flow:

1. Create and authorise a VRP mandate
2. Retrieve user data with the VRP mandate identifier

📘

Environments

Ensure that you use the same environment for all of your requests to TrueLayer APIs.

• If you are in the sandbox environment, your requests should use truelayer-sandbox.com.
• If you are in the live environment, your requests should use truelayer.com.

Create and authorise a VRP mandate

The variable recurring payments flow uses a mandate id to retrieve customer data for signup. You also need to ensure that the signupplus and recurring_payments:sweeping scopes are enabled.

Integrate variable recurring payments with Payments v3

Before you send API requests to Signup+, you need to integrate with the Payments API v3. Specifically, you need to integrate variable recurring payments.

See the Payments API v3 documentation or the payments quickstart guide for more about how to integrate.

Create a VRP mandate

After you've integrated the Payments API v3, you need to create a mandate. Signup+ doesn't support the recurring_payments:commercial scope, so you must use sweeping for the mandate type. You must also set the related_products object with the value of signup_plus in your mandate request.

If successful, when you create your mandate you receive a response containing a mandate id, user id and resource_token. Use the mandate id to retrieve user data with Signup+.

Authorise the VRP mandate

After a mandate has been created, your user needs to authorise it. If you try to use Signup+ with an unauthorised mandate, you receive a 422 Invalid Mandate State error.

Use any of the authorisation methods available for the Payments API v3 (web, mobile or direct integration). If the user authorises the mandate successfully, it has a status of authorized.

If you use the hosted payment page to authorise your payment mandate, you need to add signup=true as a hash parameter to the URL, like in this example:

https://payment.truelayer-sandbox.com/mandates#signup=true&mandate_id=6755dacf-7dd8-4577-ba11-667b6aca8474&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJwZW5ueWRldi1lNTkzOGEiLCJqdGkiOiI2NzU1ZGFjZi03ZGQ4LTQ1NzctYmExMS02NjdiNmFjYTg0YmYiOjE2MzQ2Mzk1NDQsImV4cCI6MTYzNDY0MDQ0NCwiaXNzIjoiaHR0cHM6Ly9hcGkmRldiIsImF1ZCI6Imh0dHBzOi8vYXBpLnQ3ci5kZXYifQ.vlEvoSdFv8g7t21RlXYyus01uEZlalK89P4Ii7Avl_8&return_uri=http://localhost:3000/redirect

Retrieve user data with the mandate id

Now that you have a mandate id, you can make a GET request to the /signup-plus/mandates endpoint. When you make your request, ensure you include your access_token as a bearer token. Include your mandate id as a query parameter.

Below is an example of a GET request for mandates to the Signup+ endpoint:

https://api.truelayer-sandbox.com/signup-plus/mandates?mandate_id={mandate_id}

If your request is successful, you receive a response with user data presented like this:

{
    "title": "Mr",
    "first_name": "Joe",
    "last_name": "Blogs",
    "date_of_birth": "2000-06-20",
    "address": {
        "address_line1": "Flat 1a",
        "address_line2": "Angels Court, Foxtrot Street",
        "city": "Stockport",
        "state": "Edgeley",
        "zip": "SK3 9LQ",
        "country_code": "GB"
    },
    "account_details": {
        "sort_code": "04-01-02",
        "account_number": "41921234"
    }
}

Next Steps

If you want, learn how to make payouts or refunds.