Test endpoints in Insomnia

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

Insomnia is a desktop HTTP client capable of sending HTTP requests in a configurable and visually understandable manner. Insomnia can utilise plugins to alter requests before sending them to the server.

As Payments API v3 requires request signing for interactions, to make testing in Sandbox easier for you, Truelayer provides an Insomnia plugin that can take care of signing for you when you are testing in sandbox.

In summary, you can use Insomnia to test our endpoints in sandbox while not having to worry about request signing.

Before you begin

Download the following:

  1. Insomnia Core
  2. Private key.

๐Ÿ“˜

Import our Insomnia collection

Run in InsomniaRun 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 JSON file.
  • You should expect to see one folder per endpoint for all Payments API v3 endpoints available.

Step 2: Installing TrueLayer's Insomnia signing 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 the 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).
898898

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

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.

Did this page help you?