Variable recurring payments integration

Learn how to integrate Signup+ with the VRP flow.

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.

If you properly configure it, when you create your mandate you receive a response containing a mandate id, user id and resource_token. You will use the mandate id later to retrieve user data with Signup+.

Authorise the VRP mandate

After creation, your user needs to authorise your mandate. 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. If the user authorises the mandate successfully, it has a status of authorized.

📘

Signup+ authorisation with the HPP

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 idas 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 such as below:

{
    "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 required, learn how to make payouts or refunds.