Payments API v3: requirements

Requirements for v3

When migrating from a previous version, it’s important to acknowledge new requirements and concepts introduced in Payments v3:

It is now mandatory to sign all POST API requests, including both pay-ins and payouts.

You must also include additional user data within payment creation requests.

Payment creation and authorisation are now two distinct concepts. They are handled in two separate stages in the user flow.

Each of those concepts is explained here in more detail.

Signing requests and validation of received webhook signatures

All Payments v3 API requests need to be signed (including both pay-ins/deposits, payouts and refunds).

As you can see in the link, we provide guidance on how to create certificates, upload your public key to Console and use our backend signing libraries to help out with the signing process. Note that we strongly recommend using our signing libraries for easier integration.

We also provide backend signing libraries to verify the Tl-Signature of received webhooks.

Enabling Payments in Console

Please see the section about Payments API in Console in our documentation.

Basically, to first enable the Payments section in Console, you will be required to upload your public certificates. Once you do that, you shall be able to configure you other settings (including the 'webhook URI' and 'UI customisation' options for the Payments v3 UI/UX component.

Additional user data for pay-in and payout requests

As a regulated Financial/Payment Institution we have a regulatory requirement to screen all in/out transactions from/to the merchant accounts against sanctions lists. The requirement applies to all transactions by clients who are not fully regulated and authorised financial services in the UK or EU.

TrueLayer conducts sanction and AML screening on all transactions to and from your merchant account. We double-check transactions made by end users whose name matches an individual on a sanction list.

If a transaction is flagged by sanction and/or AML screening, we will issue a Request for Information (RFI) to collect additional information required for us to investigate.

To reduce the number of RFIs raised due to sanctions investigations, the additional fields date of birth and address need to be included in the API request.

Pay-In: required user information in the payment request

🚧

End user details are required, but whether or not all of these fields are required depends on your regulatory status. For detailed requirements, get in touch with your Sales contact.

Example 1: user object for a Pay-In to an External Account (eg. your corporate bank account)

 "user":
    {
        "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
        "name": "Jonathan Sandbridge",
        "email": "[email protected]",
        "phone": "+44123456789"
    }
}

Example 2: user object for a Pay-In into a Merchant Account

 "user":
    {
        "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
        "name": "Jonathan Sandbridge",
        "email": "[email protected]",
        "phone": "+44123456789",
        "date_of_birth": "1992-11-28",
        "address":
        {
            "address_line1": "1, Hardwick Street",   	
            "address_line2": "Floor 1",
            "city": "London",
            "state": "London",
            "zip": "EC1R 4RB",
            "country_code": "GB"
        }
    }
}

Open-loop Payouts: required user information in the payment request:

Example:

POST /payouts
{
  "merchant_account_id": "c6ba13f2-35ef-4556-a99e-a6afd6275044",
  "amount_in_minor": 100,
  "currency": "GBP",
  "beneficiary": {
    "type": "external_account",
    "reference": "Withdrawal",
    "account_holder_name": "John Smith",
    "account_identifier": {
      "type": "sort_code_account_number",
      "sort_code": "<sort code>",
      "account_number": "<account number>"
    },
    "date_of_birth": "1992-08-03",
    "address": {
      "address_line1": "1 Hardwick St",
      "address_line2": "Clerkenwell",
      "city": "London",
      "state": "London",
      "zip": "EC1R 4RB",
      "country_code": "GB"
    }
  }
}

Integration options

TrueLayer offers different integration options for our Payments API v3 to suit your needs.

With Payments v3 pay-ins (deposits into your merchant account), once the payment is created from the backend, there is an additional step in which you take the end user to authorise the payment. Essentially, payment creation is now separate from payment authorisation (ie user bank selection and payment confirmation).

Payments v3 also comes with desktop and mobile UX/UI components that can be used out of the box to implement the pay-in user flow for every supported provider and country.

For the payment authorisation step, we recommend that you use our embedded payment page (EPP) or hosted payment page (HPP). Both will reduce the time and resources required since it is optimised for the best user experience (see the docs for more).

However, if you currently have a v2 or PayDirect API integration, you may already have a customised and white labelled user flow. In this case, you can keep your existing front-end screens and logic in v3 and opt for a Direct API integration (see the section on this below.)

Embedded payment page (EPP)

The embedded payment page enables you to quickly and simply add instant bank payments to your website, with a prebuilt user interface that speeds up the integration process.

The EPP acts as a modal in your web page environment. It offers enhanced customisation functionality, QR code authentication, and built-in localisation covering local languages and authentication flows for a range of European countries.

This is built to handle the nuances of bank and country requirements across the UK and Europe for you. Which means your country rollout will be fast and efficient if you are looking into expanding open banking payments into Europe. For German banks that have embedded flow approval processes, you must use the EPP, SDK or HPP to allow your users to pay with these banks due to European regulations.

Hosted payment page (HPP)

The hosted payment page is TrueLayer’s localised hosted browser solution for both mobile and desktop which can be used for the bank selection and payment confirmation page (including a QR code handoff option for a desktop to mobile app flow).

This is built to handle the nuance of bank and country requirements across the UK and Europe for you. This will increase the speed and efficiency of your country rollout if you are looking into expanding open banking payments into Europe. For German banks that have embedded flow approval processes, you must use the HPP (or SDK/EPP) to allow your users to pay with these banks (due to European regulations).

You can configure the HPP to match the look and feel of your desktop environment so that the customer journey remains seamless.

Mobile SDKs for Android and iOS

Use TrueLayer’s mobile SDK solution to embed the bank selection and payment confirmation pages into your mobile app.

You can configure the SDKs to match the look and feel of your mobile environment.

Direct API integration and keeping your custom white labelled frontend

It’s possible that you’d like to keep your current white labelled frontend and use a direct API integration, handling payment authorisation using TrueLayer APIs from the backend.

This may be true especially if you are migrating from PayDirect, which already required that you customised your frontend flow since no UX/UI components were available out of the box for it.

Again, if you are going to operate outside of the UK, you may have to handle more complex flows coming from additional bank-specific requirements. In that case we strongly recommend adopting our hosted payment page or embedded payment page. These automatically handle all additional bank flow requirements out of the box.

TrueLayer Console and Payments v3

The Console is TrueLayer’s back office platform where you can find all the credentials you need to start using our APIs in both sandbox and live environments. In Console you will also be able to check payments into and out of your merchant account, track their status and run reports.

When you open an app in Console, the tab menu includes sub-sections for:

• Payments, which displays a table of pay-ins to and payouts from your merchant account, and the ability to issue refunds.
• Settings, such as webhook and redirect URIs, and your client ID and secret.
• Merchant Account information, including available and historical balances.
• UI customisation options for the HPP, EPP, and more.

Learn more about Console in our documentation.

Quick start guides and other docs

Learn about and get started with Payments V3.

You can try out the API endpoints with our Insomnia collection and use our Insomnia plugin to sign requests quickly. You can follow the instructions in our payments quickstart guide to learn how to set up Insomnia, import the TrueLayer signing plug-in, import the Payments V3 collection and make your first payment.

Choose from which Legacy API you are migrating from

Previous legacy payments API versions all have different features and characteristics.

Recommended steps to migrate to v3 could differ based on different factors; for eg, what is your current API version (v1, v2, PayDirect?), if you are currently using TrueLayer merchant account for also doing payouts, how your current font end-user interface is configured and other factors (for example if you eventually want to expand into certain EU countries).

Start by choosing from which Payments API version you are currently integrated and coming from:

• Payments v1 API - Single Immediate Payments to your bank account (not using TrueLayer merchant account)
• Payments v1 API with Merchant Account - Pay-in into TrueLayer merchant account and Payouts v1
• Payments v2 API - Single Immediate Payments to your bank account (not using TrueLayer merchant account)
• PayDirect API - Pay-in into TrueLayer merchant account and Closed-Loop/Open-Loop Payouts