Payments API basics

The Payments API v3 allows you to make and accept payments and payouts in the UK and EU.

For a detailed list of providers that we support by country, create a Console account and visit the Supported Providers page in Console.

In general, when we talk about payments in this guide, we are referring to payments that your user makes to your account. When we talk about payouts or refunds, we mean payments that you make to your user's bank account. Most Payments API features require a merchant account to use.

The diagram below illustrates the direction of payments and payouts to and from a merchant and user account.

These are the four key types of payments covered on this page:

• Pay-ins
  A payment made from your user's account to your merchant account (pay-in) or bank details (single payment).
• Variable recurring payments (VRP)
  A series of payments made based on a mandate that determines payment amount and frequency.
• Payouts
  A payment made from your merchant account to a user account.
  These can be closed-loop payouts or open-loop payouts. Note that to make payouts, you must also have the Payouts product.
• Refunds
  A payment or payments, made back to your user, up to an amount that your user paid you initially.
  You do not need the Payouts product to enable refunds.

Payment journey: pay-ins and VRPs

The two types of payment that your user can make using the Payments API are pay-ins and variable recurring payments.

Below is a summary of the flow of a pay-in or variable recurring payment from an external account:

1. Authentication

The first step of a payment is authentication. Authentication has two parts:

• Generate public and private keys and upload them to Console.
• Generate an access token with the appropriate scopes.

2. Payment creation

After you have authenticated, you can create a payment or mandate. Before you start, it's a good idea to test in the sandbox environment with our Insomnia collection.

Once you're familiar with how to create payments with the API, you can choose an integration method to integrate these payments into your application.

On success, the API returns a payment id, which you use for the next step of the payment: authorisation.

3. Payment user authorisation

To initiate a payment or authorise a VRP mandate from your user's account, your user must give their consent to do so. The user interface they see in your app must clearly explain the nature of the payment, along with regulatory information.

The simplest way to ensure that your UI is well-designed and compliant is to use prebuilt payment authorisation UIs, such as our hosted payment page, embedded payment page, iOS, Android or React Native SDKs. Alternatively, you can build your own UI with a direct API integration.

4. Payment monitoring

To ensure that a payment has settled into your account, you need to check its status. We recommend that you configure webhooks to do this.

If you're receiving payments to your merchant account, you can also use the payments view in Console. This exportable database of incoming and outgoing transactions is also useful for operational and finance teams.

📘

Creating payments on a mandate

The VRP journey is similar to the payment journey. However, you use an authorised mandate as the payment destination when you create a VRP. Learn more in our VRP guides.

Payment journey: payouts and refunds

The two types of payout that you can make from your merchant account are payouts and refunds.

The general flow of a payout looks like this:

1. Authentication

The first step to make a payout from your merchant account is authentication. Much like payment authentication, to authenticate a payout you need:

• public and private keys, uploaded to Console.
• an access token with appropriate scopes.

2. Payout creation

Unlike a payment from an external account to you, a user doesn't need to authorise a payout or refund from your merchant account.

After you create a payout, it's immediately sent to the bank for processing and your request returns an id. You can use this id to monitor the status of your payout.

3. Payment monitoring

After you make a payout or refund, monitor its status with webhooks or the API.

You can also monitor incoming and outgoing transactions on the merchant account dashboard and payments view in Console.

Low-code integrations

Use ecommerce plugins or payment links to accept payments with a low/no-code integration process.

Start using Payments

Before you can receive or make any payments with the Payments API you need to configure request signing and generate an access token to authenticate your requests.

If you want to start testing quickly, take a look at the Payments quickstart guide, or using the Payments API Insomnia collection.

After you have an access token, you can configure authorisation via a TrueLayer web or mobile authorisation UI, or a direct API integration. You can then create different payment types and test in our sandbox environment.

For a full list of the steps you need to take to integrate our products, see our integration checklists for pay-ins and payouts.