Create a payment

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 set up request signing so you can create a Tl-signature header for your request.
Generate an access token to include as a bearer token for your request.
This should also have the payments scope).

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.

Parameter	Description
`amount_in_minor`	The 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.
`currency`	The 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.type`	The 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_selection`	This 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_selection`	This 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.type`	Configuration 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_name`	The name of the beneficiary. 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_identifier`	The 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.reference`	The 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.
`user`	An 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.
`metadata`	An 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:

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:

Field	Description
`id`	The 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.