Make a test payment

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

In this guide, you'll install Insomnia, create a free merchant account and make your first test payment in the UK with the Payments API v3.

📘

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 in-depth payments integration guide.

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

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

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

To use the Payments API v3, you need a public and private key pair. 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.

To check which version of either software you have on your device, run this command in your terminal:

openssl version

If you do not 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. The keys you generate will save to your current directory.

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

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.

Download the TrueLayer Insomnia collection

If you have Insomnia installed, download and install the TrueLayer collection.

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

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.

1960

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. Make sure 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": "{One of your redirect URIs set in **Console** > **Settings**}",
	"CLIENT_ID": "{Your client_id}",
	"CLIENT_SECRET": "{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
}

🚧

Not seeing 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:

556

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

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.

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.

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.

Create a payment and check its status

  1. Open the Pay-Ins folder within the Insomnia collection.
  2. Open the Pay-In to Merchant Account folder.
  3. Open the Pay-in with Hosted Payment Page 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.

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 Pay-In to Merchant Account > Pay-in with Hosted Payment Page > Create HPP.
  2. 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 return URI in the URI below with the id and resource token you generated earlier. The return URI must be one of the Allowed redirect URIs from Console > Settings. This URI determines where the user is taken after the payment.

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

The default return URIs are https://console.truelayer.com/redirect-page and http://localhost:3000/callback.

The complete link should look like this:

583

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

Copy and paste it into your browser.

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.
  6. Enter a test username, test_executed for a successful payment, and any three digits for the PIN, then click Continue.
  7. 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. 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.