Upload your public key and create a merchant account

\n \t\t

2.Configure Insomnia

\n \t\t

\n \t\t

3. Create and authorise a payment

\n \t\t

\n \t\t\t

4. Use Signup+ to get user information

\n \t\t

\n\n" } [/block] The Payments API v3 authenticates requests using [request signing](/docs/sign-your-payments-requests) as well as a bearer `access_token` for additional security. All requests must be signed using public and private keys. As such, we recommend using Insomnia to start testing our API, as the TrueLayer Insomnia plugin simplifies the request signing process. ### 1.1. 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. If you don't 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. ```bash Private key generation command openssl ecparam -genkey -name secp521r1 -noout -out ec512-private-key.pem ``` Then, to generate your public key, run this command in your terminal. ```bash Public key generation command openssl ec -in ec512-private-key.pem -pubout -out ec512-public-key.pem ``` The keys you generate 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. ### 1.2. Create a Console account If you don't already have one, you need a Console account to upload your keys and access your API credentials. > 🚧 Use the same app as your payments integration > > If you have an existing payments integration, you should use the same app and `client_id` for your Signup+ integration as you do for Payments v3. 1. Go to Console and click **Sign up** to create an account. 2. Click the link you receive by email to verify your registration. A form displays. 3. In the form, provide some personal and company information and set your marketing preferences. A dialog displays. 4. In the dialog, set an application name (you can't change this later). A page displays confirming your new **Application name**, **Client ID**, and **Client secret**. 5. Download or make a note of your client secret, then click **Get started**. You have now created a Console account and are signed in. ### 1.3. Upload your private key and create a merchant account 1. Ensure you're signed into Console and that the sandbox environment is enabled (**Live** toggled off in the top-right corner). 2. Select **Payments** in the left navigation bar and then the **GET STARTED** button. 3. Select the file upload option in the middle of the dialog, select your public key, then click **Upload public key**. 4. Enter a merchant account name then select **Create**. Now you've created a merchant account, new settings display in the Payment section, such as **Settings** and **Merchant account**. ### 1.4. Install Insomnia Download and install Insomnia. We recommend you use version 2023.1 of Insomnia, as this version supports request chaining after an import, and doesn't need you to sign in. Use these links to download Insomnia version 2023.1 for: - MacOS - Windows Once you've installed this, we recommend that you disable automatic updates within the **Insomnia Preferences** menu. ### 1.5. Import the TrueLayer Insomnia collection Once Insomnia is installed, download the TrueLayer collection from this link by clicking **Run Payments API v3**. Alternatively, you can download the collection as a file from Github here. To import this file in Insomnia: 1. Open a project. 2. Click **Create** in the top-right corner and select **Import from > File**. 3. Select the collection file you downloaded from Github. 4. Click **Scan**. A preview of the Insomnia resources displays. 5. Click **Import**. ## 2. Configure Insomnia [block:html] { "html": "

1. Prepare keys and Insomnia

\n \t \t\t

Upload your public key and create a merchant account

\n \t\t

2.Configure Insomnia

\n \t\t

\n \t\t

3. Create and authorise a payment

\n \t\t

\n \t\t\t

4. Use Signup+ to get user information

\n \t\t

" } [/block] Now that you've installed Insomnia, you can 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. In the TrueLayer Insomnia collection, you must define and add properties to ensure your requests can communicate with your Console account. You also need to ensure you have the TrueLayer Insomnia plugin installed. This simplifies request signing, so you can quickly test requests. ### 2.1. Set properties in the collection To add properties, you should edit the **Sandbox Environment** that the TrueLayer Insomnia collection contains. To do this: 1. Click the environment switcher in the top-left corner. By default, **Sandbox Sample Env** is selected. [block:image]{"images":[{"image":["https://files.readme.io/28a7f48577e59183f51c1e1d9447c651b457cdf3cd83da23524fc057091f2246-Manage-Environments-location.png","",""],"align":"center","sizing":"70% "}]}[/block] 2. Click **Manage Environments**. 3. The **Sandbox Sample Env** contains several properties you should provide. These are: - `CLIENT_ID`: This is the client_id you can find this on the [**Application settings** page in Console](https://docs.truelayer.com/docs/application-settings). - `CLIENT_SECRET`: You got this when you created your app in Console. - `CERTIFICATE_ID`: You can find this labelled as **KID** on the [**Payments settings** page in Console](/docs/payments-settings). - `PRIVATE_KEY`: You should have generated this key [earlier on this page](/docs/quickstart-use-signup-with-a-payment#11-generate-keys). You need to replace each line break in your private key with `\n`. This process is explained below. - `RETURN_URI`: The link that your users (or you, when testing) are redirected to after a successful payment. Ensure this is included in your [**Redirect URIs** on the **Application Settings** page in Console](/docs/application-settings#redirect-uris). 4. After you've updated your properties, click **Close** to save your changes. #### Format your private key The Insomnia environment uses JSON, which doesn't 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`, you can 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 a command in terminal to replace each line break with `\n`, like this: `awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' file_location/cert-name.pem` Your `PRIVATE_KEY` property will look like this after formatting: [block:image] { "images": [ { "image": [ "https://files.readme.io/7d4ad4c-Private_Key_Example.png", "Private Key Example.png", 556 ], "align": "center", "caption": "An example of a private key with line breaks replaced with `\\n`." } ] } [/block] ### 2.2. Install the TrueLayer Insomnia plugin The TrueLayer Insomnia plugin ensures that your requests are securely signed with your public and private keys. To install the plugin from within Insomnia: 1. Open the **Insomnia Preferences** window by clicking the **Preferences** button in the bottom-left corner. 2. Select the **Plugins** tab. 3. Enter `insomnia-plugin-jws-by-truelayer` in the **npm-package-name** field, then click **Install Plugin**. Alternatively, you can download the plugin from the **Insomnia Plugin Hub**. 4. Ensure that **Enable?** is toggled to the left of the plugin name. [block:image]{"images":[{"image":["https://files.readme.io/60fab04118e1ac8e283ebc9ebc6c6a249b07922f0c2ad430370a554492b9970e-Plugins-tab.png",null,"When the plugin is installed correctly, the Plugins tab looks like this."],"align":"center","sizing":"70% ","caption":"When the plugin is installed and enabled correctly, the Plugins tab looks like this."}]}[/block] If you've 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. ## 3. Create and authorise a payment [block:html] { "html": "

1. Prepare keys and Insomnia

\n \t \t\t

Upload your public key and create a merchant account

\n \t\t

2.Configure Insomnia

\n \t\t

\n \t\t

3. Create and authorise a payment

\n \t\t

\n \t\t\t

4. Use Signup+ to get user information

\n \t\t

" } [/block] To make a test payment, you need to generate an access token, create a payment, and then create a hosted payment page link based on the payment. Then, you'll play the role of an end user and complete the payment yourself. ### 3.1. Generate an access token 1. Open the **1. Authentication** folder in the Insomnia collection. 2. Select the **1C. Generate Access Token - Signup+** request. 3. Click **Send**. If the POST request is successful, it returns a 200 response that contains an `access_token`. Insomnia saves this token and use it as a **Bearer** token in future requests. If your request fails, make sure that you set up your environment properly, and have it selected in the environment selector. ### 3.2. Retrieve your merchant account details 1. Open the **2. Merchant Accounts** folder in the Insomnia collection. 2. Select the **2A. 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. Alternatively, you can get your merchant account ID in the [**Merchant Account** dashboard in Console](/docs/merchant-account-dashboard). Here, you can also check the balance of your account, and see transactions. Make a note of your GBP merchant account `id`. ### 3.3. Create a payment 1. Open the **7. Signup+** folder in the Insomnia collection. 2. Open the **Standard pay-in** folder. 3. Select the **7A. Create Payment** request. 4. Select **Send**. 5. In the **Beneficiary Merchant Account ID** prompt that displays, enter your GBP merchant account `id`. You received this from the **2A. List merchant accounts** request in the previous section. If the POST request is successful, it returns a 201 response like this: ```json Example payment response { "id": "7620aa1d-b188-4941-b85f-8dc9a76c202e", "user": { "id": "67638fba-8412-4233-b57c-35b9bd0f4542" }, "resource_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2FwaS50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJpc3MiOiJodHRwczovL2FwaS50cnVlbGF5ZXItc2FuZGJveC5jb20vcGF5bWVudHMtZ2F0ZXdheSIsImV4cCI6MTcyNTU0NTI1NywiaWF0IjoxNzI1NTQ0MzU3LCJuYmYiOjE3MjU1NDQzNTcsInNjb3BlIjoicGF5bWVudCIsImNsaWVudF9pZCI6InNhbmRib3gtdG9tdGVzdC1hNGQ0MzIiLCJqdGkiOiI3NjIwYWExZC1iMTg4LTQ5NDEtYjg1Zi04ZGM5YTc2YzIwMmUifQ.An35dBLoMCUmsLJ0NJILm_UPyfFkNW7lhZa38A78SbRjTwr6jbsoLnvvxAornnt9jgE8E3IjxyBwQJwVInOOS2N0zeRqia7eGyVwbQEgJQP0tZ1VibyjzlD738LXgBy_moPrpZsQjbBuqLol5cqo7zvHR9cBnuTEJh995qiMnesu8RE9Dg75-uLBshqzg9beMNTveRt5DhaDJCG1v2g-VzM2Q116oFDaNsMhWwYWrC-vpg-t4JbYP9tht033OWlt7TLG-YG7SNTB5E0WPYD0f6lYNRWhWDP9_uhDLKxDXIlPeHfhZzQWOwvt94JFRS6ldQAn3U1bg6FH_TVKIOQvFg", "status": "authorization_required" } ``` This table explains the four objects you get in the response: [block:parameters] { "data": { "h-0": "Object name", "h-1": "Description", "0-0": "`id`", "0-1": "The payment `id`. \n \nThis represents the payment, and you can use it to authorise the payment or get information about it.", "1-0": "`user.id`", "1-1": "The `id` that's part of the `user` object represents the user that made the payment. \n \nYou can optionally provide one at payment creation to link multiple payments together.", "2-0": "`resource_token`", "2-1": "The `resource_token` for the payment. \n \nYou use this to authorise the payment. It expires after 15 minutes.", "3-0": "`status`", "3-1": "The [status of the payment](/docs/payment-statuses), which explains which part of the authorisation journey it's in. \n \nAt creation, it has a status of `authorization_required`. If authorised and successful, it should transition through `authorized` and `executed`, into `settled`. \n \nYou can track a payment's status with webhooks, the [**Payments** page in Console](/docs/payments-view), or with the GET payment endpoint. \n \nYou can test the GET payment endpoint with request **3A. Get payment status** in Insomnia." }, "cols": 2, "rows": 4, "align": [ "left", "left" ] } [/block] ### 3.4. Create a hosted payment page link At this point, you've initiated a payment to your sandbox merchant account. However, it still has a status of `authorization_required`. You can optionally check this with the **3A. Get payment status** request in the Insomnia collection. However, a payment can't executed and be sent by a bank until it's authorised by a user. You also can't use Signup+ unless a payment has a status of `settled`. TrueLayer offers a range of [payment authorisation user interfaces](/docs/payment-authorisation-basics) that you can integrate so users can authorise payments. For this guide, we'll use the [hosted payment page](/docs/hosted-payment-page), as it's the quickest and easiest to get an immediate result with. The hosted payment page is a payment authorisation flow, hosted on TrueLayer's servers. You substitute certain parts of the URL you access this page through to ensure you authorise the right payment. #### Use the Insomnia to create a hosted payment page link To create a hosted payment page automatically based on a payment you've already created with the **7A. Create payment** request in Insomnia: 1. Open the **7D. Create HPP** request. If they're not already open from the previous request, you need to open the **7. Signup+ > Standard pay-in** folders. 2. Select the **Query** tab. 3. Select the copy to clipboard icon within the **URL Preview** box. [block:image]{"images":[{"image":["https://files.readme.io/8cfc2a6353126ab6db7bcd55751768fd7a22b138295f3efd46b638e4ddbedce3-Location-of-HPP-URL-preview-and-clipboard-button.png","",""],"align":"center","sizing":"70% "}]}[/block] If you completed these steps, you should have a link to use in [step 3.5](/docs/quickstart-use-signup-with-a-payment#35-authorise-the-payment). If the URL preview isn't displaying, ensure that the options that say **Response → Body Attribute** in the URL above are properly filled. > 🚧 > > Note that the user interface for this step varies in different versions of Insomnia ([we recommend version 2023.1](/docs/quickstart-use-signup-with-a-payment#14-install-insomnia)). The general procedure should remain largely the same however. #### 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](/docs/quickstart-use-signup-with-a-payment#33-create-a-payment), 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`. #### An example of a HPP link If you've created a HPP link through one of the two methods above, it should look like this. You'll use this link in the next step. [block:image] { "images": [ { "image": [ "https://files.readme.io/e16b22b-HPP_Link_Example.png", "HPP Link Example.png", 583 ], "align": "center", "caption": "An example of a HPP link with the `id`, `resource_token` and `Redirect URI` substituted. \nThis example is an image, as you should not copy and paste it, as the existing values won't work." } ] } [/block] ### 3.5. Authorise the payment Now that you've created 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 guide, we complete the flow on desktop. > 📘 > > The authorisation process is a bit different in sandbox compared to a live payment. > > For example, a user's name wouldn't be `test_executed`. However, the flow does resemble live payment authorisation. Wherever you access the **Mock UK Bank** website in this flow, you would instead access a bank's app or website instead. To authorise your payment: 1. Access the hosted payment link you created in the previous step in a browser. 2. The hosted payment page asks you to **Choose your bank**. In a UK sandbox payment, there's only one available option. There is also a grey option that highlights how a live bank would display if it's undergoing maintenance. [block:image]{"images":[{"image":["https://files.readme.io/72a84de31559841d1a2e83d21eb8dcf393ad86a305a43b3dd7e20763b6c4d2fd-Provider-selection-screen-in-HPP.png","",""],"align":"center","sizing":"70% "}]}[/block] 3. Select the **Mock UK Payments - Redirect Flow** bank. 4. Select **Go to bank**. 5. Select **Or continue on desktop**, which opens the Mock UK Bank page. You can instead scan the QR code on a mobile device, but the process will be different to this guide. 6. Enter the username `test_executed` and any three digits for the PIN, then select **Continue**. There are other options available, which you can test later. [Learn more in our sandbox documentation](/docs/test-payments-in-sandbox). 7. Select an account to pay from (they're not real accounts), then click **Continue**. After the page finishes loading, the payment is authorised. Once the payment is complete, you can check your merchant account in a few ways. The easiest is to look for it on the [**Payments** page in Console](/docs/payments-view). Here you'll see details of the test payment, including the amount, the remitter, the timestamp, and its status. The payment should transition quickly through the `executed` status to the `settled` status, depending on what you specified to the mock bank. When you integrate in the live environment, you should use [webhooks](/docs/payments-api-webhook-reference) to check your payment's progress. You've now made a payment in sandbox. Congratulations! Now, we'll use Signup+ to retrieve some sandbox user data, using the id of our payment with the `settled` status. ## 4. Use Signup+ to retrieve user information [block:html] { "html": "

1. Prepare keys and Insomnia

\n \t \t\t

Upload your public key and create a merchant account

\n \t\t

2.Configure Insomnia

\n \t\t

\n \t\t

3. Create and authorise a payment

\n \t\t

\n \t\t\t

4. Use Signup+ to get user information

\n \t\t