Make a payment

Learn how to prepare for and make a payment quickly in our sandbox environment.

The Payments API v3 is the latest and recommended version of the TrueLayer Payments API. This guide explains how to make your first payment.

Insomnia makes authentication and security with request signing simpler, so we use it for this guide. However, you can integrate the Payments API v3 without using Insomnia.

There are three steps to making a payment:

  1. Prepare keys and install Insomnia
  2. Configure Insomnia
  3. Make a Payment
17621762

Prepare keys and install Insomnia

The Payments API v3 authenticates using request signing as well as a bearer token for additional security. Requests are signed using public and private keys. As such, we use Insomnia for testing this API, as the TrueLayer Insomnia plugin makes it easier to sign requests.

Generate keys

In order to use the Payments API v3, you need a public and private key pair. You can generate these via any method, but we recommend OpenSSL on Windows or LibreSSL on macOS or Linux. These methods are usually available on these operating systems by default.

To check the version currently installed on your device, run this command in your terminal:

openssl version

If you do not have either the OpenSSL or LibreSSL library installed on your device, install the latest version from the official website.

Once OpenSSL is installed on your device:

  1. To generate your private key, run the following command in your terminal.
openssl ecparam -genkey -name secp521r1 -noout -out ec512-private-key.pem
  1. To generate your public key, run the following command in your terminal.
openssl ec -in ec512-private-key.pem -pubout -out ec512-public-key.pem

When you run these commands in your terminal, the keys save to your current directory.

Upload public key to Console and create merchant account

  1. Go to Console, and ensure to toggle to Sandbox in the top right.
  2. Optionally, if you haven't created an application in Console yet, click CREATE APP in the top-left corner and create an app.
  3. Click on Payments API, then select GET STARTED.
  4. Upload your public key file.
  5. Enter a name for your merchant account.
    This is optional, but you should create a merchant account as we'll make a payment to it later.

Install Insomnia

Download and install Insomnia from here. Insomnia is a REST API client similar to Postman, which you can use to test calls more easily.

Configure Insomnia

Now that you've installed Insomnia, you must configure it in order to make a payment. The TrueLayer Insomnia plugin we will install ensures that your requests are securely signed with your public and private keys generated earlier.

Next, the TrueLayer Insomnia collection contains a variety of pre-configured requests you can use to test the Payments API v3 quickly. Within this collection, you must define some properties to ensure your requests can communicate with your Console account.

Download the TrueLayer Insomnia collection

If you have Insomnia installed, you should be able to download and install the TrueLayer collection by clicking this button:

Run in InsomniaRun in Insomnia

If this doesn't work, and the collection downloads as a file:

  1. Open the Insomnia application, then open Preferences.
  2. Open the Data tab.
  3. Click Import Data, then select From File.
  4. Select and import the downloaded file.

Install the TrueLayer Insomnia plugin

  1. Open the Insomnia application, then open Preferences.
  2. Open 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 to check the toggle under Enable? to enable the plugin.

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

Set properties in the collection

Now that you've installed Insomnia and have the plugin enabled, you must set properties within the collection. These are used in the JSON web signature header for authentication. To set properties:

  1. Click the environment dropdown in the top-left corner, then select Manage Environments.
  2. Select the TrueLayer sub-environment.
    You can also set properties in the base environment, but properties set in the sub-environment override these.
  3. Set the properties in the TrueLayer environment as below.
{
    "ENVIRONMENT_URI": "https://api.truelayer-sandbox.com",
    "AUTH_SERVER_URI": "https://auth.truelayer-sandbox.com",
    "RETURN_URI": "{Enter a redirect URI set in Console > Settings}",
    "CLIENT_ID": "{Enter your client_id from Console}",
    "CLIENT_SECRET": "{Enter your client secret, downloaded when you created your app in Console}",
    "CERTIFICATE_ID": "{Enter the public key ID saved in the Payments > Settings section of Console}",
    "PRIVATE_KEY": "{Enter the content from your private key file}",
    "REQUIRE_JWS": true
}

Format of private key property

JSON does not allow line breaks. This means that when you set the value for your PRIVATE_KEY property, you must replace each line break with the newline character \n. This means your PRIVATE_KEY property should look like the image below.

556556

An example of a private key with line breaks replaced with \n.

You can use any method to replace each line break in the private key property with \n. For example:

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

Make a payment

If your properties are set properly, it's simple to authenticate and then make a payment. Before you start, ensure that you select the TrueLayer environment in the top-left corner of Insomnia.

There are several methods you can use to make a payment. You can choose to use TrueLayer's hosted payment page, our Android and iOS SDKs, or an API only solution. This guide makes a payment with the hosted payments page.

Generate an access token

  1. Open the Authentication folder within the Insomnia collection.
  2. Select the Generate Access Token request.
  3. Click Send.
    If the POST request is successful, it returns a 200 response that contains an access_token value. This token is saved and used as a Bearer token in future requests within the collection.

Retrieve your merchant account details

  1. Open the Merchant Accounts folder within the Insomnia collection.
  2. Select the 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.

You can check these merchant accounts within the Console sandbox within Payments > Merchant Account.

Create a payment and check its status

  1. Open the Payments folder within the Insomnia collection.
  2. Open the Create a payment to a Merchant Account folder.
  3. Open the Using TrueLayer's Hosted Payment Page for provider selection folder.
  4. Select the Create Payment request.
  5. Click Send.
  6. Enter the id you received from the List merchant accounts request earlier.
    You should use the ID for the GBP account.
  7. Enter a value in the Name, User Email, and Phone dialogs that display. These can be anything, as they are for a test payment in the Sandbox environment.
    Is the POST request is successful, it returns a 201 response that contains an id, which is the payment ID. It also contains a user, associated id, and a resource_token.

Create a hosted payment page link

At this point, you've created a payment to your sandbox merchant account. However, the status of the payment is authorization_required, which you can check with the Get Payment Status request.

In order to authorise and complete the payment, we must generate a link to the hosted payment page. We can then access that and complete the payment, in the same way a customer would.

To generate the link, substitute the id, resource token, and Redirect URI in the URI below:

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

Use the id and resource_token generated in the previous step. The Redirect URI must be one of the Allowed redirect URIs from Console > Settings. The Redirect 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.

Once you've prepared the link, it should look like the image below:

583583

An example of a HPP link with the id, resource_token and Redirect URI substituted.

Complete the payment

Now that you've generated 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. Here we show the flow for desktop.

  1. Access the link you created in the previous step in a browser.
    The hosted payment page displays. There's only one bank available as it's the sandbox environment.
  2. Select the Mock UK Payments - Redirect Flow bank.
  3. Click Continue to your bank.
  4. Either:
    • Scan the QR code on a mobile device.
    • Or click Or continue on desktop.
  5. Enter a test username, test_executed for a successful payment, and any three digits for the PIN, then click Continue.
  6. Select an account to pay from, then click Continue.
    After the page finishes loading, the payment is complete.

Once the payment is complete, you can check your merchant account in Console > Payments > Merchant Account. This contain details of the test payment, such as the amount, the remitter, and time of payment.

Next Steps

You've now made a payment in the sandbox. You can experiment with various other features in the Payments v3 API. For example, you could:

  • Check the Payments API reference to learn about the other requests you can make.
  • Use the Get Payment status request in the Insomnia collection to see how the status of a payment changes at different steps of a payment, or if the user takes different actions.
  • Use the id of the settled payment to initiate a refund using the Create the Refund request within the Insomnia collection.
  • Learn more about recurring payments and mandates.

Did this page help you?