Console

Create a payment

Build an API call to initiate a payment in GBP or EUR.

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. You must:

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. TrueLayer supports GBP and EUR.

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.bank_transfer.scheme_selectionThis parameter lets you select whether to display providers that support instant or non-instant payment schemes for the payment (within Europe).

You can also choose to prepopulate the scheme, or let the user choose a scheme.

Learn more about scheme 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_holder_nameThe name of the beneficiary. This is what displays as the beneficiary on the remitter's bank statement.

In a pay-in to a merchant account, this takes priority as the name the user sees on their statement. However, if omitted in a pay-in to a merchant account, the name associated with the merchant account is used by default.

Some providers have upper limits for this field. If you need to shorten a name to fit these limits, we recommend removing middle names first, then initialising the first name. For example:

- Jonathan Alexander Doe
- Jonathan Doe
- J Doe
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.

If a payment is made into your merchant account's sort code and account number or IBAN instead of its merchant account id, it has a webhook of external_payment_received.
payment_method.beneficiary.referenceThe reference for the payment that will appear on your user's bank statement.

Some providers have character limits for this field. We recommend making your reference as short as possible.
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.

Some providers have character limits for the remitter name field. If you need to shorten a name to fit these limits, we recommend removing middle names first, then initialising the first name. For example:

- Jonathan Alexander Doe
- Jonathan Doe
- J Doe

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.
related_productsAn optional field for adding related products, at least one product should be set.
Not available when creating recurring payments.

🚧

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:

curl --request POST \
     --url https://api.truelayer-sandbox.com/v3/payments \
     --header 'Idempotency-Key: string' \
     --header 'Tl-Signature: string' \
     --header 'accept: application/json; charset=UTF-8' \
     --header 'content-type: application/json; charset=UTF-8' \
     --data '
{
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": [
          "DE"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ]
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "verification": {
        "type": "automated"
      },
      "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
      "account_holder_name": "Ben Eficiary",
      "reference": "payment-ref"
    }
  },
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
    "name": "Remi Terr",
    "email": "[email protected]",
    "phone": "+447777777777",
    "date_of_birth": "1990-01-31"
  },
  "amount_in_minor": 1
}

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 remitter.

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. It expires after 15 minutes, which causes the payment to fail.

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",
  "status": "authorization_required"
}

🚧

Transfer limits

Be aware that some banks have limits on the amount that you can transfer in one payment. These are usually very high, but speak to us if you plan on making very high-value transactions.

EUR transfer limits tend to be higher than limits in GBP.

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 about 2 months ago