Create a payment using our HTTP flow

You can make payments into an external bank account or your Truelayer-managed merchant account with open banking infrastructure using our APIs.

This guide focuses on making a payment into an external bank account. Payments API v3 is also capable of facilitating payments to Truelayer-managed merchant accounts. See our documentation to find out more about merchant accounts.

📘
Check out the API reference for Payments API v3
Refer to the API reference for further information on creating a payment

Before you begin

Set up your public key on Console.
Set up your webhook URI on Console.
Get an access_token with the scope payments in Console. You'll need this value in the Authorization header of your request, with the Bearer prefix.
Configure request signing.

🚧
Requests should be signed
All the requests in this guide should be signed on your server/backend.

🚧
All requests need an idempotency key
All the requests in this guide should include an idempotency key. You can learn more about API idempotency.

Make a payment initiation request

Make a POST request to /payments endpoint with the following parameters :

Field	Description
`payment_method`	Method of the payment. Values: bank_transfer
`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: GBP 1 = 100 pence
`payment_method.beneficiary`	Destination of the payment. Different types include `external_account` and `merchant_account`. Both cases are built for different use cases.
`payment_method.provider_selection`	You can set your provider selection method using this field. Currently two types are supported: `user_selected` `preselected` `user_selected` type will allow a selection to happen later during the authorisation flow, meanwhile `preselected` will permanently correlate the created payment with the passed `provider_id`.
`payment_method.provider.provider_id`	If a `preselected` provider type is selected
`beneficiary.scheme_identifier`	The scheme of the account identifier. Values: scan
`user`	The user authorising the payment.
`user.id`	If it is a returning user, this field should be populated to avoid creating a brand new user.
`user.name`	Name field is optional. However, unregulated clients need to provide this value, otherwise the response will have the status code 400 with the relevant error message
`user.phone`	`phone` field is optional. However, unregulated clients need to provide either `user.phone` or `user.email`, otherwise the response will have the status code 400 with the relevant error message
`user.email`	`email` field is optional. However, unregulated clients need to provide either `user.phone` or `user.email`, otherwise the response will have the status code 400 with the relevant error message

The following example shows the request body of a payment initiation:

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]"
  }
}

If the payment initiation is successful, you'll get a response with the following fields:

Field	Description
`id`	ID of the created payment resource
`user.id`	If an `id` was passed during the creation, the same ID will be present in this field, representing the existing user at Truelayer. If no `id` was passed during the creation, this field will be populated with the newly generated ID for the new user.
`resource_token`	Short-lived (15 minutes), limited token with authorisation to interact with the created payment. The main purpose of this token is to provide the frontend components the authorisation to start the authorisation flow and take the payment through the flow. Learn more about authorising payments.

Field

Description

id

ID of the created payment resource

user.id

If an id was passed during the creation, the same ID will be present in this field, representing the existing user at Truelayer. If no id was passed during the creation, this field will be populated with the newly generated ID for the new user.

resource_token

Short-lived (15 minutes), limited token with authorisation to interact with the created payment. The main purpose of this token is to provide the frontend components the authorisation to start the authorisation flow and take the payment through the flow.

Learn more about authorising payments.

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

A newly-created payment will have the status authorization_required. The payment needs to through an authorisation flow to have the funds reach the beneficiary. We provide multiple options to authorise payments.

Create a payment using our HTTP flow

📘
Check out the API reference for Payments API v3

Before you begin

🚧
Requests should be signed

🚧
All requests need an idempotency key

Make a payment initiation request

📘Check out the API reference for Payments API v3

Before you begin

🚧Requests should be signed

🚧All requests need an idempotency key

Make a payment initiation request

📘
Check out the API reference for Payments API v3

🚧
Requests should be signed

🚧
All requests need an idempotency key