⚡️ Quickstart: Use Signup+ with a payment

📘

This guide is very similar to the quickstart guide that explains how to make a test payment. This is because when you use Signup with a payment, you just need to make one extra call to the /signup-plus/payments endpoint with the payment id.

In this guide, you'll create a free UK merchant account, complete a sandbox payment with the Payments API v3, then use Signup+ to retrieve user information about the person making the payment.

Although much of the guide focuses on how to configure your integration, when you make the payment, you will authorise it as if you were an end user.

To follow the guide, you will need to install Insomnia and download our collection of API requests.

Quickstart overview

There are four steps you need to complete in this quickstart guide to get user information through Signup+ with a payment:

1. Prepare keys and Insomnia: Generate signing keys and install the Insomnia application for this guide.
2. Configure Insomnia: Install our Insomnia plugin and set up associated parameters.
3. Create and authorise a payment: Create a payment and authorise it with our mock bank.
4. Use Signup+ to get user information: Call the Signup+ endpoint to get data based on your payment.

1. Prepare keys and install Insomnia

The Payments API v3 authenticates requests using request signing as well as a bearer access_token for additional security. All requests must be signed using public and private keys. As such, we recommend using Insomnia to start testing our API, as the TrueLayer Insomnia plugin simplifies the request signing process.

1.1. Generate keys

To use the Payments API v3, you need public and private keys. You can generate these however you want, but we recommend OpenSSL on Windows or LibreSSL on macOS or Linux. These methods are usually available on these operating systems by default.

If you don't have either OpenSSL or LibreSSL installed on your device, go to their website to install the latest version.

To generate your private key, run the following command in your terminal.

openssl ecparam -genkey -name secp521r1 -noout -out ec512-private-key.pem

Then, to generate your public key, run this command in your terminal.

openssl ec -in ec512-private-key.pem -pubout -out ec512-public-key.pem

The keys you generate save to your current directory. To find out where this is, input "pwd" on Mac or "cd" on Windows into your terminal, and hit Enter.

1.2. Create a Console account

If you don't already have one, you need a Console account to upload your keys and access your API credentials.

🚧

Use the same app as your payments integration

If you have an existing payments integration, you should use the same app and client_id for your Signup+ integration as you do for Payments v3.

1. Go to Console and click Sign up to create an account.
2. Click the link you receive by email to verify your registration.
   A form displays.
3. In the form, provide some personal and company information and set your marketing preferences.
   A dialog displays.
4. In the dialog, set an application name (you can't change this later).
   A page displays confirming your new Application name, Client ID, and Client secret.
5. Download or make a note of your client secret, then click Get started.
   You have now created a Console account and are signed in.

1.3. Upload your private key and create a merchant account

1. Ensure you're signed into Console and that the sandbox environment is enabled (Live toggled off in the top-right corner).
2. Select Payments in the left navigation bar and then the GET STARTED button.
3. Select the file upload option in the middle of the dialog, select your public key, then click Upload public key.
4. Enter a merchant account name then select Create.
   Now you've created a merchant account, new settings display in the Payment section, such as Settings and Merchant account.

1.4. Install Insomnia

Download and install Insomnia. We recommend you use version 2023.1 of Insomnia, as this version supports request chaining after an import, and doesn't need you to sign in. Use these links to download Insomnia version 2023.1 for:

• MacOS
• Windows

Once you've installed this, we recommend that you disable automatic updates within the Insomnia Preferences menu.

1.5. Import the TrueLayer Insomnia collection

Once Insomnia is installed, download the TrueLayer collection from this link by clicking Run Payments API v3.

Alternatively, you can download the collection as a file from Github here. To import this file in Insomnia:

1. Open a project.
2. Click Create in the top-right corner and select Import from > File.
3. Select the collection file you downloaded from Github.
4. Click Scan.
   A preview of the Insomnia resources displays.
5. Click Import.

2. Configure Insomnia

Now that you've installed Insomnia, you can configure it to make a payment.

The TrueLayer Insomnia collection contains a variety of pre-configured requests you can use to test the Payments API v3.

In the TrueLayer Insomnia collection, you must define and add properties to ensure your requests can communicate with your Console account. You also need to ensure you have the TrueLayer Insomnia plugin installed. This simplifies request signing, so you can quickly test requests.

2.1. Set properties in the collection

To add properties, you should edit the Sandbox Environment that the TrueLayer Insomnia collection contains. To do this:

1. Click the environment switcher in the top-left corner.
   By default, Sandbox Sample Env is selected.

   

2. Click Manage Environments.

3. The Sandbox Sample Env contains several properties you should provide. These are:

   • CLIENT_ID: This is the client_id you can find this on the Application settings page in Console.
   • CLIENT_SECRET: You got this when you created your app in Console.
   • CERTIFICATE_ID: You can find this labelled as KID on the Payments settings page in Console.
   • PRIVATE_KEY: You should have generated this key earlier on this page.
     You need to replace each line break in your private key with \n. This process is explained below.
   • RETURN_URI: The link that your users (or you, when testing) are redirected to after a successful payment. Ensure this is included in your Redirect URIs on the Application Settings page in Console.

4. After you've updated your properties, click Close to save your changes.

Format your private key

The Insomnia environment uses JSON, which doesn't allow line breaks. So, when you set the value for the PRIVATE_KEY property, you must replace each line break with the newline character \n. To edit the content of your PRIVATE_KEY, you can open the private key file in a text editor.

You can use any method to do this. For example:

• manually editing the private key in a text editor or Insomnia, replacing each line break with \n.
• using a command in terminal to replace each line break with \n, like this:
  awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' file_location/cert-name.pem

Your PRIVATE_KEY property will look like this after formatting:

2.2. Install the TrueLayer Insomnia plugin

The TrueLayer Insomnia plugin ensures that your requests are securely signed with your public and private keys.

To install the plugin from within Insomnia:

1. Open the Insomnia Preferences window by clicking the Preferences button in the bottom-left corner.

2. Select the Plugins tab.

3. Enter insomnia-plugin-jws-by-truelayer in the npm-package-name field, then click Install Plugin.
   Alternatively, you can download the plugin from the Insomnia Plugin Hub.

4. Ensure that Enable? is toggled to the left of the plugin name.

   

If you've already installed the plugin before you click the Install Plugin button, an error displays: "Failed to install insomnia-plugin-jws-by-truelayer". Check that the plugin is enabled.

For more information about the plugin, and other installation methods, see our GitHub page.

3. Create and authorise a payment

To make a test payment, you need to generate an access token, create a payment, and then create a hosted payment page link based on the payment. Then, you'll play the role of an end user and complete the payment yourself.

3.1. Generate an access token

1. Open the 1. Authentication folder in the Insomnia collection.
2. Select the 1C. Generate Access Token - Signup+ request.
3. Click Send.

If the POST request is successful, it returns a 200 response that contains an access_token. Insomnia saves this token and use it as a Bearer token in future requests.

If your request fails, make sure that you set up your environment properly, and have it selected in the environment selector.

3.2. Retrieve your merchant account details

1. Open the 2. Merchant Accounts folder in the Insomnia collection.
2. Select the 2A. List Merchant Accounts request.
3. Click Send.

If the GET request is successful, it returns a 200 response with an id for both the GBP and EUR accounts, along with other details.

Alternatively, you can get your merchant account ID in the Merchant Account dashboard in Console. Here, you can also check the balance of your account, and see transactions.

Make a note of your GBP merchant account id.

3.3. Create a payment

1. Open the 7. Signup+ folder in the Insomnia collection.
2. Open the Standard pay-in folder.
3. Select the 7A. Create Payment request.
4. Select Send.
5. In the Beneficiary Merchant Account ID prompt that displays, enter your GBP merchant account id.
   You received this from the 2A. List merchant accounts request in the previous section.

If the POST request is successful, it returns a 201 response like this:

{
  "id": "7620aa1d-b188-4941-b85f-8dc9a76c202e",
  "user": {
    "id": "67638fba-8412-4233-b57c-35b9bd0f4542"
  },
  "resource_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2FwaS50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJpc3MiOiJodHRwczovL2FwaS50cnVlbGF5ZXItc2FuZGJveC5jb20vcGF5bWVudHMtZ2F0ZXdheSIsImV4cCI6MTcyNTU0NTI1NywiaWF0IjoxNzI1NTQ0MzU3LCJuYmYiOjE3MjU1NDQzNTcsInNjb3BlIjoicGF5bWVudCIsImNsaWVudF9pZCI6InNhbmRib3gtdG9tdGVzdC1hNGQ0MzIiLCJqdGkiOiI3NjIwYWExZC1iMTg4LTQ5NDEtYjg1Zi04ZGM5YTc2YzIwMmUifQ.An35dBLoMCUmsLJ0NJILm_UPyfFkNW7lhZa38A78SbRjTwr6jbsoLnvvxAornnt9jgE8E3IjxyBwQJwVInOOS2N0zeRqia7eGyVwbQEgJQP0tZ1VibyjzlD738LXgBy_moPrpZsQjbBuqLol5cqo7zvHR9cBnuTEJh995qiMnesu8RE9Dg75-uLBshqzg9beMNTveRt5DhaDJCG1v2g-VzM2Q116oFDaNsMhWwYWrC-vpg-t4JbYP9tht033OWlt7TLG-YG7SNTB5E0WPYD0f6lYNRWhWDP9_uhDLKxDXIlPeHfhZzQWOwvt94JFRS6ldQAn3U1bg6FH_TVKIOQvFg",
  "status": "authorization_required"
}

This table explains the four objects you get in the response:

3.4. Create a hosted payment page link

At this point, you've initiated a payment to your sandbox merchant account. However, it still has a status of authorization_required. You can optionally check this with the 3A. Get payment status request in the Insomnia collection.

However, a payment can't executed and be sent by a bank until it's authorised by a user. You also can't use Signup+ unless a payment has a status of settled.

TrueLayer offers a range of payment authorisation user interfaces that you can integrate so users can authorise payments. For this guide, we'll use the hosted payment page, as it's the quickest and easiest to get an immediate result with.

The hosted payment page is a payment authorisation flow, hosted on TrueLayer's servers. You substitute certain parts of the URL you access this page through to ensure you authorise the right payment.

Use the Insomnia to create a hosted payment page link

To create a hosted payment page automatically based on a payment you've already created with the 7A. Create payment request in Insomnia:

1. Open the 7D. Create HPP request.
   If they're not already open from the previous request, you need to open the 7. Signup+ > Standard pay-in folders.

2. Select the Query tab.

3. Select the copy to clipboard icon within the URL Preview box.

   

If you completed these steps, you should have a link to use in step 3.5. If the URL preview isn't displaying, ensure that the options that say Response → Body Attribute in the URL above are properly filled.

🚧

Note that the user interface for this step varies in different versions of Insomnia (we recommend version 2023.1). The general procedure should remain largely the same however.

Create the link manually

To generate the link, substitute the id, resource token, and Redirect URI in the URI below with the id and resource token you generated earlier, and your Redirect URI from Console:

https://payment.truelayer-sandbox.com/payments#payment_id={id}&resource_token={resource_token}&return_uri={Redirect URI}

The Redirect URI must be one of the Allowed redirect URIs from Console > Settings. This URI determines where the user is taken after the payment. The default URIs are https://console.truelayer.com/redirect-page and http://localhost:3000/callback.

An example of a HPP link

If you've created a HPP link through one of the two methods above, it should look like this. You'll use this link in the next step.

3.5. Authorise the payment

Now that you've created a hosted payment page link, you can access it and complete the payment as a user would. You can do this on either desktop or mobile. In this guide, we complete the flow on desktop.

📘

The authorisation process is a bit different in sandbox compared to a live payment.

For example, a user's name wouldn't be test_executed. However, the flow does resemble live payment authorisation. Wherever you access the Mock UK Bank website in this flow, you would instead access a bank's app or website instead.

To authorise your payment:

1. Access the hosted payment link you created in the previous step in a browser.

2. The hosted payment page asks you to Choose your bank.
   In a UK sandbox payment, there's only one available option. There is also a grey option that highlights how a live bank would display if it's undergoing maintenance.

   

3. Select the Mock UK Payments - Redirect Flow bank.

4. Select Go to bank.

5. Select Or continue on desktop, which opens the Mock UK Bank page.
   You can instead scan the QR code on a mobile device, but the process will be different to this guide.

6. Enter the username test_executed and any three digits for the PIN, then select Continue.
   There are other options available, which you can test later. Learn more in our sandbox documentation.

7. Select an account to pay from (they're not real accounts), then click Continue.
   After the page finishes loading, the payment is authorised.

Once the payment is complete, you can check your merchant account in a few ways. The easiest is to look for it on the Payments page in Console. Here you'll see details of the test payment, including the amount, the remitter, the timestamp, and its status. The payment should transition quickly through the executed status to the settled status, depending on what you specified to the mock bank.

When you integrate in the live environment, you should use webhooks to check your payment's progress.

You've now made a payment in sandbox. Congratulations! Now, we'll use Signup+ to retrieve some sandbox user data, using the id of our payment with the settled status.

4. Use Signup+ to retrieve user information

Now that you have a settled payment, you can get user information from its id, such as name, date of birth, and address.

In your live integration, you will then use this information to simplify the signup flow for your user.

4.1. Get information with the payment id

To test the Signup+ endpoint, you need to provide the id you got in response when you created the payment in step 3.3. You used this to create your HPP link. Copy this to your clipboard.

Then, you should run the 7C Get Signup+ data for standard payment request. A prompt displays where you should paste your payment id. If you used the default value of 1 for the amount_in_minor for your payment, you should receive user information for "Tommie Burke". The response looks like this:

{
  "first_name": "TOMMIE",
  "last_name": "BURKE",
  "date_of_birth": "2008-09-05",
  "address": {
    "address_line1": "339",
    "address_line2": "IDVERIFIER ST",
    "city": "ELY",
    "state": "CAMBS",
    "zip": "CB6 2AG",
    "country_code": "GB"
  },
  "account_details": {
    "sort_code": "40-22-25",
    "account_number": "14375270",
    "iban": "GB75CLRB04066800000871",
    "provider_id": "mock-payments-gb-redirect"
  }
}

You receive a variety of information in the response, including the user's full name, date of birth, address, bank details, and the bank they paid with. You can use these to simplify their signup process.

If the request fails with a 400 error, it means that you didn't make the request within 15 minutes of payment creation. Repeat steps 3.1 through 4.1.

Testing different scenarios

The result you get from Signup+ through request 7C. Get Signup+ data for standard payment change based on the value of amount_in_minor in your payment request.

You can change the amount_in_minor in request in 7A. Create payment. To do this, click the JSON tab and edit the body of your API request appropriately.

This table explains the different scenarios you can test. These include different sets of test user data and errors.

4.2. Simplify the signup flow

In the response to your request in the previous step, we received a variety of information about the user:

• first_name
• last_name
• date_of_birth
• address
• account_details

For most products, you can use this information to prepopulate the signup flow for the user. This means a user should only need to provide their preferred contact details and credentials when they sign up for your product.

This flow shows an example payment and signup flow, and highlights which parts of the UI are built by TrueLayer, the bank, or yourself.

4.3. Signup flow design considerations

There are several choices you can make when designing your signup flow UI. There are also regulatory requirements you need to follow.

See our Signup+ UX guide for more information on best practices and how to implement Signup+ as part of your flow.

Display collected information in the flow

The fifth step in the example flow above isn't optional. You must display the user information collected through Signup+ to the user as part of the payment flow.

Set deposit limits before the payment

We recommend that you enable your users to specify their deposit limits before they choose their payment amount. This avoids any potential issues with users depositing more than their limit permits, which would require a manual refund.

Collect email before the payment

You can collect the user's email address at payment creation so you don't need to collect any information immediately after the payment, simplifying the flow.

Additionally, if you already have a user's email in your system, you can prompt them to sign in before the payment instead of creating a new account through Signup+. You should use whatever process you have in place to prevent duplicate account creation.

Optional step: Test age verification and Signup+

📘

We recommend this for live integrations

Although we say that age verification is optional in this quickstart guide, this is because you need to have the feature enabled before you can test it.

If you're going live with Signup+, we recommend that you use age verification. As verification tells you whether identity data is available for a user, you or if they're using an invalid account. This means you can adapt your integration flow appropriately.

TrueLayer offers age verification before a payment as part of the Signup+ product. This means that a remitter's date of birth is checked before a payment.

However, in order to test this, you need to contact us in order to enable this to test it in the sandbox environment.

If you've contacted us and enabled this, you can use the requests in the 7. Signup+ > Pay-in with age verification folder in Insomnia to test this feature.

The steps to age verification and Signup+ remain largely the same as the procedure explained on this page. However, the amount_in_minor in the body of the 7D. Create payment request determines what test scenario you experience.

Use these values for amount_in_minor to test different scenarios:

With age verification, if the user's date of birth is under 18, the payment fails before it touches your merchant account. This means if you test this scenario, you'll never actually use the Signup+ endpoint to retrieve user data for that user.