Console

Create a payment using our HTTP flow

Learn how to make a payment initiation request using our HTTP flow.

Suggest Edits

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 start

  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.

🚧

Idempotency

All requests should include an idempotency key.

Make a payment initiation request

Make a POST request to the /payments endpoint with the following parameters (full reference in POST /payments) :

FieldDescription
amount_in_minorThe 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
currencyCurrency of the payment in ISO 4217.

You cannot make a payment from GBP currency to a EUR account, specified in the payment_method.beneficiary.account_identifier field.
payment_methodConfiguration options for the payment method.
payment_method.provider_selectionYou can set your provider selection method using this field.
- user_selected: Allow a selection to happen later during the authorisation flow.
- preselected: Permanently correlate the created payment with the passed provider_id.
payment_method.provier_selection.remitterIf the provider is preselected, the remitter can be preselected too.
payment_method.provider_selection.filterConfiguration options to constrain which providers should be available during the provider_selection action.
payment_method.provider_selection.filter.excludesConfiguration options to constrain which providers should be excluded during the provider_selection action.
payment_method.provider_selection.scheme_selectionOptional configuration options to specify the type of scheme selection.
- instant_only: Only allow providers that support instant payments.
- instant_preferred: Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable.
payment_method.beneficiaryConfiguration options for beneficiary of the payment.
- merchant_account: Pay into a wallet for close-loop payments
- external_account: Pay to an account by specifying the account identifier.
payment_method.beneficiary.account_identifierIdentifies the destination account.

This can be a sort_code_acc or iban. Note that you cannot make payments from a GBP account to a EUR account, or the other way round.
userThe user authorising the payment.
If it is a returning user, the id field should be populated to avoid creating a brand new user.
metadataOptional field for adding custom key-value data to a resource. This is saved on payment creation and returned on every payment retrieve.

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:

FieldDescription
idID of the created payment resource.
user.idIf 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_tokenA limited token with a life of 15 minutes. Authorised to interact with the created payment. The main purpose of this token is to authorise the frontend components to start the authorisation flow and take the payment through the process.

Learn more about authorising payments.
statusStatus of the payment.
Learn more about payment statuses.
{
  "id": "string",
  "user": {
    "id": "{UUID}"
  },
  "resource_token": "a-secret-token"
}

A newly created payment has the status authorization_required. The payment needs to go through an authorisation flow before the money reaches the beneficiary. We provide multiple options to authorise payments.

Updated 2 months ago