Console

Create a payment

Build an API call to initiate a payment.

Suggest Edits

Before you start

In order to create a payment, you must first set up authentication. Authentication for the Payments API has two parts:

Your requests to the payments API should also include an idempotency key, which you can provide in the Idempotency-Key header.

Make a payment request

To create a payment, make a POST request to the /payments endpoint, providing values for the parameters below. See the full API reference for more details.

ParameterDescription
amount_in_minorThe amount in minor units.

Minor units are the smallest units of a currency, depending on the number of decimals. For example: 1 GBP = 100 pence.
currencyThe currency of the payment as an ISO 4217 code.

You cannot make a payment from GBP currency to a EUR account, specified in the payment_method.beneficiary.account_identifier object.
payment_method.typeThe payment method for the payment.

For a single payment, use bank_transfer not mandate, which is for variable recurring payments.
payment_method.bank_transfer.provider_selectionThis parameter lets you select how users can choose a provider.

- user_selected: Enables the user to select a provider as part of the authorisation flow.
- preselected: Enables you to prepopulate the provide for the payment you create with a provider_id.

There are also options to specify which providers a user can select from, or to filter by certain criteria.

Learn more about provider selection.
payment_method.beneficiary.typeConfiguration options for the beneficiary of the payment.

- merchant_account: Pay into your merchant account. This is required for closed-loop payments.
- external_account: Pay to an account by specifying the account identifier.
payment_method.beneficiary.account_identifierThe identifier for the beneficiary's account.

This can be sort_code_account_number, iban, bban or nrb.

Note that you cannot make payments from a GBP account to a EUR account, or the other way round.
userAn identifier of the user making the payment.

For a single payment, it's mandatory to include the payer's full name and one of their email address or phone number.

Learn more about user details for payments.
metadataAn optional field to add custom data to a payment. This is saved on payment creation and returned on every payment retrieve.

🚧

Integration options

Although the example on this page uses HTTP, we also offer complete .NET and Java libraries you can use to integrate payment creation.

Below is an example of a payment creation request using HTTP:

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: random
Tl-Signature: {SIGNATURE}
Authorization: Bearer {TOKEN}
Host: api.truelayer-sandbox.com
{
  "amount_in_minor": 1000,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "",
      "reference": "reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "xx-xx-xx",
        "account_number": "xxxxxxx"
      }
    },
    "provider_selection": {
      "type": "user_selected"
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Payment response

If the payment initiation request is successful, you receive a response that contains the following fields:

FieldDescription
idThe ID for the created payment.
user.id An ID for the payer.

An ID is generated automatically if you leave the user id blank when you create the payment.

If you use the same id as a previous payment, both payments will be associated with the ID.
resource_token A token used to authorise the created payment. Has a slimited duration of 15 minutes.

The main purpose of this token is to authorise the frontend components of the authorisation flow, which must be completed for the payment to execute.

You can authorise payments with TrueLayer's web or mobile app UI, or a direct API integration.
status The status of the payment.

The example below shows the structure of the payment creation response:

{
  "id": "string",
  "user": {
    "id": "{UUID}"
  },
  "resource_token": "a-secret-token"
}

Detailed parameters to configure

The information you provide for certain parameters will change based on the payment type and purpose.

Provider selection

You can configure provider selection through the payment_method.bank_transfer.provider_selection parameter. Learn about the different provider selection methods.

User information

Provide user information alongside created payments through the user parameter. This is important to:

  • Provide mandatory user details to prevent money-laundering (not required if you have a PISP license).
  • Associate multiple payments with a single user ID so they can be retrieved easily.

Updated 20 days ago