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 start
- Set up your public key on Console.
- Set up your webhook URI on Console.
- Get an
access_token
with the scopepayments
in Console. You'll need this value in theAuthorization
header of your request, with theBearer
prefix. - 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) :
Field | 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: GBP 1 = 100 pence |
currency | Currency 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_method | Configuration options for the payment method. |
payment_method.provider_selection | You 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.remitter | If the provider is preselected, the remitter can be preselected too. |
payment_method.provider_selection.filter | Configuration options to constrain which providers should be available during the provider_selection action. |
payment_method.provider_selection.filter.excludes | Configuration options to constrain which providers should be excluded during the provider_selection action. |
payment_method.provider_selection.scheme_selection | Optional 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.beneficiary | Configuration 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_identifier | Identifies 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. |
user | The user authorising the payment. If it is a returning user, the id field should be populated to avoid creating a brand new user. |
metadata | Optional 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:
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 | A 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. |
status | Status 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