⚡️ Quickstart: Make a test payment

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

In this guide, you'll create a free UK merchant account and complete your first test payment with the Payments API v3. You will initiate a payment and authorise it as if you were an end user. (For this example payment, you will use the hosted payment UI for authorisation.)

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


Interested in EU payments?

In this guide, you'll make a test payment in GBP, with a UK merchant account in sandbox. Payments in Europe are very similar, but sometimes need extra considerations. Learn more about these in our documentation about single payments and payment configuration, as well as our EU payments guide.

This is a three-stage process. You need to:

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

1. Prepare keys and install Insomnia

The Payments API v3 authenticates using request signing as well as a bearer token for additional security. All requests must be 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

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. This will generate the path to the directory where your keys are saved. If you do not have either OpenSSL or LibreSSL installed on your device, go to their website to install the latest version.

For Windows, right click on Command Prompt in the Start menu. Select Run as Administrator from the dropdown menu. Then, copy the path to the folder you want to use OpenSSL from.

Go back to Command Prompt or terminal. Type cd , add a space, paste the address and press Enter.

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 will 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.

Upload your public key to Console and create a merchant account

  1. Go to Console, and ensure the sandbox environment is enabled (Live should be greyed out in the top right of the screen).
  2. Click on Payments API, then select GET STARTED.
  3. Upload your public key file.
  4. Create and name a merchant account.

Install Insomnia

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

Import the TrueLayer Insomnia collection

Download the TrueLayer collection from this link.

  1. Open Insomnia and click the home icon to navigate to Personal Projects.
  2. Click Create and select Request Collection. This will create a new collection and take you to that page.
  3. At the top of the screen, click the My Collection dropdown and select Import/Export.
  4. Click Choose a file and select the TrueLayer collection.
  5. Click Scan.

2. Configure Insomnia

Now that you've installed Insomnia, 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. Within this collection, you must define some properties to ensure your requests can communicate with your Console account.


Our Insomnia collection. Use the subenvironment for test API calls.

Install the TrueLayer Insomnia plugin

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

  1. Open the Insomnia application, then open the Preferences menu with the button in the bottom left of the window.
  2. Open the Plugins tab.
  3. Enter insomnia-plugin-jws-by-truelayer in the npm-package-name field, then click Install Plugin. Or you can download the plugin from the Insomnia Plugin Hub.
  4. Ensure that Enable? is toggled.
When the plugin is installed correctly, the Plugins tab looks like this.

When the plugin is installed and enabled correctly, the Plugins tab looks like this.

Note that if you have 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.

Set properties in the collection

Now that you've installed Insomnia and have the plugin enabled, set properties within the collection. You'll use these in the JSON web signature header for authentication.

To set properties:

  1. In the breadcrumbs at the top of the screen, click Insomnia.
  2. Click the environment dropdown in the top left corner, then select Manage Environments.
  3. Select the TrueLayer sub-environment. You can also set properties in the base environment, but properties set in the sub-environment override these.
  4. Set the properties in the TrueLayer sub-environment. You can do this by copying and pasting the entire code block below, replacing the placeholders in curly braces with their actual values.
	"ENVIRONMENT_URI": "https://api.truelayer-sandbox.com",
	"AUTH_SERVER_URI": "https://auth.truelayer-sandbox.com",
	"RETURN_URI": "{This is your redirect URI, found in **Console** > **Settings**}",
	"CLIENT_ID": "{Enter your client_id}",
	"CLIENT_SECRET": "{Enter your client_secret}",
	"CERTIFICATE_ID": "{Enter the value under **KID** in **Console** > **Payments** > **Settings**}",
	"PRIVATE_KEY": "{Enter the content from your private key file}",
	"REQUIRE_JWS": true


Can't see TrueLayer sub-environments?

Go to Manage Environments and click the + button next to Sub Environments. Copy and paste the variables in the above code block into your new environment, and substitute their values as normal.

Format your private key

JSON does not 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, 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 this command in your terminal to replace each line break with \n
    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' file_location/cert-name.pem

Your PRIVATE_KEY property will look like this after formatting:


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

3. Make a payment

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

1. 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. Insomnia will save this token and use it as a Bearer token in future requests.

2. 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 the balance of your merchant accounts, and review all recent payments into and out of the account, in Console > Payments > Merchant Account.

3. 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. Use the ID for the GBP account.
  7. Enter a value in the Name, User Email, and Phone dialogs that display. This is just a test payment, so these can be anything.

If the POST request is successful, it returns:

  • a 201 response that contains a payment id
  • a user with associated id
  • a resource_token.

4. Create a hosted payment page link

Congratulations. You've now initiated a test payment to your sandbox merchant account. The status of this payment is authorization_required, which you can check with the Get Payment Status request in Insomnia.

In order to authorise and complete the payment, you need to generate a link to the hosted payment page.

Use the Build HPP request to create a hosted payment page link

  1. In Insomnia, go to Create a payment to an External Account > Using TrueLayer's Hosted Payment Page for provider selection > Create HPP.
  2. Click Send.
  3. Navigate to the Query tab below the URL. Your HPP URL will be in the URL Preview box.

Copy and paste the link into your browser.

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.

The complete link should look like this:


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

Copy and paste it into your browser.

5. 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: in this tutorial, you'll go through the flow for desktop.

  1. Access the link you created in the previous step in a browser.
  2. The hosted payment page asks you to choose your provider. Because you're in sandbox, you will only see one option.
  3. Select the Mock UK Payments - Redirect Flow bank.
  4. Click Continue to your bank.
  5. Either:
  • Scan the QR code on a mobile device.
  • Or click Or continue on desktop.
  1. Enter a test username, test_executed for a successful payment, and any three digits for the PIN, then click Continue.
  2. 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. Here you'll see details of the test payment, including the amount, the remitter, and the timestamp.

You've now made a payment in sandbox. Congratulations!

Next steps

You might want to experiment with various other features in the Payments v3 API using Insomnia. 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.