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 (a bank account that TrueLayer manages on your behalf) and make your first test payment with the Payments API v3.

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 from this link.

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

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
}

🚧

Retrieving the content of your private key

To get your PRIVATE_KEY value, open the private key file in a text editor. This is what you will need to set as a value in the sub-environment.

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.

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

Create a hosted payment page link

Congratulations. You've now created 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:

583

An example of a HPP link with the id, resource_token and Redirect 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.