UI design and Console [Payments V1]

This page explains the two methods you can use to create a user interface (UI) for the Payments API v1.

Integration checklist

Below are two checklists. One is for using the TrueLayer UI to initiate payments, and the other is for whitelabelling our service inside your own application.

For the best user experience and the highest conversion rate, we recommend you integrate with your own UI.

Using your own UI

1. Use our /v2/single-immediate-payments-providers endpoint to build a provider selection screen. This is the screen where your user chooses the bank they want to pay with. We provide all the assets you need to do this.
2. Obtain a client credentials grant from the authentication server.
3. Create a payment, specifying the bank the user wants to use.
4. Redirect the user to the URI specified in the API response.
5. Handle the redirect on the redirect_uri you set in the Console.
6. Poll our get info endpoint until you see a final status.

🚧

If you are unregulated as a PISP and you wish to use your own UI, you need to add this disclaimer on the screen where you confirm the details of the payment:

---

By clicking next you are permitting TrueLayer to initiate a payment from your bank account. You also agree to the TrueLayer terms and privacy policy.

For full guidance, refer to our Help Centre or reach out to our Client Care team for further information.

Using our UI

1. Obtain a client credentials grant from the auth server.
2. Create a payment.
3. Redirect the user to the URI specified in the API response.
4. Handle the redirect on the redirect_uri you set in the Console.
5. Poll our get info endpoint until you see a final status.

Get set up

Test in sandbox

To use the sandbox environment, replace truelayer.com with truelayer-sandbox.com in your requests. Make sure to use the correct credentials for sandbox.

In sandbox, you have access to any providers that have a sandbox environment. With these providers, you can send a mock payment that simulates the behaviour of a live payment.

Get your client_id and client_secret

To authenticate with our API, you need to use your client_id and client_secret for the environment you are using (live or sandbox). Find both of these values in our Console.

Start using live payment data

To upgrade your account to the live environment, you will need to give our sales team your client_id. In the sandbox area of Console, follow these steps:

1. Go to your Console > Payments API.
2. Select Go to live env.
3. Go to the Settings tab.
4. Copy the client_id field.
5. Send your client_id to our sales team.

Add a redirect_uri

Once the end user has authenticated with their bank, we will redirect them back to your application. Add this URI to Console so that we can validate it when you create a payment.

Add the redirect to the settings page. You can add as many as you like.

Offer TrueLayer payments to your users

The only UI requirement is that you must not embed the payment flow as a frame within a larger frameset. Most providers don't allow this flow and will block the user from continuing.

Running the flow as a webview should not be a problem if you want to initiate the payment from within a mobile app.

When you display the TrueLayer payment option at checkout, we recommend that you label the option as Instant bank transfer rather than mentioning TrueLayer or open banking. This increases user trust.

Authenticate

This is an example of the request you make to authenticate your Payments V1 request:

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

This is an example of the response you receive:

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use our authentication server to obtain a client credentials grant. You will need to use this in your requests to the Payments API.

Unlike with our Data API, this grant doesn’t represent a user, but a client creating the payment.