Create a payment
Build an API call to initiate 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 thepayments
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. 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.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_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. |
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. 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 using HTTP:
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]"
}
}
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 payer. 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. Has a slimited duration of 15 minutes. 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"
}
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.
Updated 20 days ago