Create a payment using our HTTP flow

Learn how to make a payment initiation request 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

  1. Set up your public key on Console.
  2. Set up your webhook URI on Console.
  3. 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.
  4. 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.

{
  "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.


Did this page help you?