Payments only integration

Learn how to integrate Signup+ with the payments only flow.

There are two ways to integrate Signup+ with payments in the UK:

  • Create a payment which is subject to automated 18+ age verification checks
  • Retrieve the remitter's identity data associated with a payment, after that payment settles

Automated 18+ age check for payments

Create payments which only settle in your merchant account if the remitter is more than 18 years old.

This integration option is a great fit for signup processes where you would like to verify that the user is of legal age, and you don't want to deal with refunding payments from remitters under the age limit.

Create a verified payment with an age check

Follow this guide and specify the beneficiary.remitter_date_of_birth flag to create a payment with an automated legal age check. You must also ensure that the payment has signup_plus specified as a related_product.

If you're testing payment verification in the sandbox environment, the result of age verification depends on the value of the amount_in_minor parameter in your payment creation request.

The possible values when you test in sandbox are:

Value of amount_in_minorSignup+ responseResponse type
Less than 1800Age not legalError
1800 to 10000Identity data foundSuccess
10000 to 25000Joint accounts not supportedError
Greater than 25000User data not foundError

🚧

Payment verification delays

Usually, TrueLayer can verify a remitter’s age after funds are held in a suspense account and transition the payment to a terminal status within 15 seconds. However, in the worst case scenario, TrueLayer’s checks can take up to 2 minutes.

If you want to cancel your onboarding flow before the payment reaches a terminal status, you must refund any payments that might settle after cancellation.

Retrieve the remitter's identity data through a settled payment

Create a payment (regular or age-verified), and then make a request to the Signup+ /signup-pluspayments endpoint to get the remitter's identity data.

To integrate Signup+ with payments, there are four key steps:

  1. Enable the signupplus scope
  2. Generate an access token with the payments and signupplus scopes
  3. Create and authorise a payment
  4. Retrieve user data with the payment id
1600

Starting from the PSU, a diagram of each step in the payments only integration flow.

1. Enable the signupplus scope

To verify that your app has the signupplus scope, go to Console > Data API > Auth link builder > Product Permissions.

The signupplus scope is available by default in the sandbox environment. To enable and use this scope in the live environment, contact Support.

2. Generate an access token with payments and signupplus scopes

To use the Signup+ API, you need an access token. Generate one by calling the /connect/token endpoint with your client credentials, using the payments and signupplus scopes.

You can also use the Signup+ Postman collection to test API requests, including the request to generate an access token.

3. Create and authorise a payment

To integrate with Signup+, you need a payment_id. To get this, create a payment. Its id will be present in the API response.

For more information, see our Payments API v3 documentation or the payments quickstart guide.

If you use the hosted payment page for end-user authorisation, ensure that you include signup_plus as a related_product when you create the payment. You only need to include this for the first payment, as this is what ensures SIgnup+ specific wording displays in the authorisation flow.

If you include the related_product, a standard HPP URL as below works for Signup+:

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

When you receive the payment_executed webhook, use the payment_id as input for Signup+.

4. Retrieve user identity data with the payment id

Once your payment is settled, use its id in a request to the Signup+ /signup-plus/payments endpoint:

https://api.truelayer.com/signup-plus/payments?payment_id={paymentId}

You must ensure that you make the request to the /signup-plus/payments endpoint within 15 minutes of the payment settling. If you don't, you receive an error stating that 'the valid period for requesting user data has expired'.

In a successful response, you'll receive the remitter's identity information in this format:

{
    "title": "Mr",
    "first_name": "Wallace",
    "last_name": "Wensleydale",
    "date_of_birth": "07/08/1959",
    "address": {
        "address_line1": "62 West Wallaby Street",
        "city": "Wigan",
        "state": "Lancashire",
        "zip": "L18 9HA",
        "country_code": "GB"
    },
    "account_details": {
        "sort_code": "{SORTCODE}",
        "account_number": "{ACCOUNTNUMBER}"
    }
}

If you're testing Signup+ in sandbox, the result of your request depends on the value of the amount_in_minor parameter in your payment creation request.

The possible responses you can receive are:

Value of amount_in_minorSignup+ responseResponse type
1800 to 1999Test user data 1: John SandbridgeSuccess
2000 to 2099Test user data 2: Anthony CarterSuccess
2100 to 2199Test user data 3: Isabella AllenSuccess
2200 to 9999Range reserved for new test users. Defaults to Test User Data 1Success
10000 to 25000Joint accounts not supportedError
25001 to 35000User data not foundError
Greater than 35000Range reserved for other scenarios. Defaults to User data not foundError

Next steps

Learn how to make payouts or refunds: