Test payment endpoints in Insomnia

Learn how to test our Payments API v3 endpoints in Insomnia.

Insomnia is a desktop HTTP client that can send HTTP requests in a configurable and visually understandable way. You can also alter requests with plugins before sending them to the server.

Payments API v3 requires request signing for interactions. To make testing easier, our Insomnia plugin can take care of signing for you.

Before you start


  1. Insomnia Core
  2. A private key.


Import our Insomnia collection

Run in Insomnia

Install plugins and set up environment

Step 1: Import the Payments API v3 collection file into Insomnia

After downloading the collection file, you need to import the file to your Insomnia. You can do this by:

  • Open Insomnia Core and go to the Preferences menu
  • Open the Data tab.
  • From the Data tab, click on the Import Data selection and choose the From File option.
  • Select and import the Insomnia Payments API collection file.
  • You should expect to see one folder per endpoint for all Payments API v3 endpoints available.

Step 2: Install the TrueLayer Insomnia plugin

  • Go to Preferences, then navigate to Plugins
  • Enter insomnia-plugin-jws-by-truelayer in the plugin bar and install the plugin.
  • Make sure to check the toggle under Enable? to verify that the plugin is enabled.

Step 3: Prepare your Insomnia account environment

In order to send requests in Insomnia, you need to set several properties within the collection. These are used in the JSON web signature header. Learn more on our Github here.

You can add properties in a few different ways:

  • Add the properties in the global environments included in the collection.
  • To add the properties at the folder level, right-click on the folder that contains the requests and click Environment.
  • A combination of both (folder level properties override global environment properties).

Insomnia screen with the dropdown for environments.

Set the following properties in your environment:

    "ENVIRONMENT_URI": "https://api.truelayer-sandbox.com",
    "AUTH_SERVER_URI": "https://auth.truelayer-sandbox.com",
    "RETURN_URI": "{Enter the return_uri you also registered on the console general settings}",
    "CLIENT_ID": "{Enter the client_id from the console app}",
    "CLIENT_SECRET": "{Enter the client secret you downloaded when you created your app on console}",
    "CERTIFICATE_ID": "{Enter the public key ID generated from 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. Your PRIVATE_KEY property should look like the image below.


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

Test the endpoints

Make sure to:

  • Include the Idempotency-Key UUID parameter in the request headers. This key should be included already in every request of the collection.
  • Trigger the request to "generate the payment token". That will generate the access token the other endpoints need to work. This generation is automatically requested for every call if there is an expired access_token, and is then shared with the other endpoints of the collection.