Initiate a payment
Learn how to make a payment initiation request with relevant information from your user.
This feature is in private beta and is currently available to a limited number of clients. To join our private beta, contact Client Care.
If you are unregulated as a PISP, you need to add the following disclaimer on the screen where you confirm the payment details with the user:
By clicking Next, you are permitting TrueLayer to initiate a payment from your bank account. You also agree to TrueLayer end-user terms and privacy policy.
For more information, see our post on displaying permissions or contact our Support team.
The initiation request includes the following fields:
Field | Type | Mandatory | Description |
---|---|---|---|
single_immediate_payment | SingleImmediatePaymentRequestDetails | Mandatory | Specifies the details of the payment to be created. |
auth_flow | AuthFlowRequestDetails | Mandatory | Specifies how the payment should be authorised. |
webhook_uri | string | Optional | An address to which payment webhooks with the status of the payment should be sent. Has to be https. |
• SingleImmediatePaymentRequestDetails
Field | Type | Mandatory | Description |
---|---|---|---|
single_immediate_payment_id | uuid | Mandatory | The unique id of the payment you want to create. If two requests are received with the same id, only the first one will be processed. |
amount_in_minor | number | Mandatory | The amount, specified in terms of the fractional monetary unit of the payment currency, to be paid. |
currency | string | Mandatory | The ISO 4217 code of the currency for the payment. |
provider_id | string | Mandatory | The id of the provider, as given on our /providers endpoint. |
scheme_id | string | Mandatory | The id of the scheme to make the payment over. This must be one of the schemes advertised by the provider on the /v2/single-immediate-payments-providers endpoint. |
fee_option_id | string | Conditional | The id indicating the desired distribution of fees between the beneficiary and remitter. Must be a fee_option_id from one of the options advertised under that scheme on the /v2/single-immediate-payments-providers endpoint. Should be omitted if there are no fee options (the scheme is free). |
beneficiary | ParticipantDetails | Mandatory | The details of the beneficiary receiving the payment. |
remitter | ParticipantDetails | Conditional | The details of the remitter sending the payment. |
references | ReferencesDetails | Mandatory | The details of the reference, or references, for the payment. |
• ParticipantDetails
Field | Type | Mandatory | Description |
---|---|---|---|
account | AccountIdentifierDetails | Mandatory | The details of the account owned by the participant. |
name | string | Conditional | The name on the participant's account. |
• AccountIdentifierDetails
Field | Type | Mandatory | Description |
---|---|---|---|
type | string | Mandatory | The type of account. Must be one of sort_code_account_number , iban , bban , or nrb . Please refer to our providers endpoint for details of what account types are supported by each provider. |
sort_code | string | Mandatory if type is sort_code_account_number . Invalid otherwise. | 6 digit sort code (no spaces or dashes). |
account_number | string | Mandatory if type is sort_code_account_number . Invalid otherwise. | 8 digit account number. |
iban | string | Mandatory if type is iban . Invalid otherwise. | Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). |
bban | string | Mandatory if type is bban . Invalid otherwise. | Valid Basic Bank Account Number (no spaces). Consists of up to 30 alphanumeric characters, with a fixed length per country. Forms the latter part of the IBAN as described above. |
nrb | string | Mandatory if type is nrb . Invalid otherwise. | Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. |
• ReferencesDetails
Field | Type | Mandatory | Description |
---|---|---|---|
type | string | Mandatory | The type of references. Must be one of single or separate , depending on whether the provider supports distinct references for the beneficiary and remitter. Please refer to our providers endpoint for details of whether a provider supports a single reference or separate references. |
reference | string | Mandatory if type is single . Invalid otherwise. | The reference to appear on the beneficiary's and remitter's statements. |
beneficiary | string | Mandatory if type is separate . Invalid otherwise. | The reference to appear on the beneficiary's statement. |
remitter | string | Mandatory if type is separate . Invalid otherwise. | The reference to appear on the remitter's statement. |
• AuthFlowRequestDetails
Field | Type | Mandatory | Description |
---|---|---|---|
type | string | Mandatory | The type of authorisation flow. Must be redirect or embedded . Providers requiring additional authorisation flows may be available in future. |
return_uri | string | Mandatory if type is redirect . Invalid otherwise. | The URI we will return the user to after authorising the payment. When the user is redirected to this URI, we will append a single_immediate_payment_id query parameter specifying the payment id and a type query parameter with value single_immediate_payment . |
psu_ip_address | string | Conditional if type is redirect . Invalid otherwise. | The IP address of the end user. |
data_access_token | string | Optional if type is redirect . Invalid otherwise. | If the provider only allows a single active consent across both AIS and PIS services, in order to prevent invalidating an existing AIS consent, you can pass the data access token on this field, and we will preserve the data consent when requesting authorisation for the payment. |
additional_inputs | dictionary<string, string> | Conditional | A dictionary of additional values required on a per-provider basis. Please refer to our providers endpoint for details of the providers that require these. |
Make a POST /v2/single-immediate-payment-initiation-requests
call:
curl -X POST \
-H "Authorization: Bearer ${access_token}" \
--data '{
"single_immediate_payment": {
"single_immediate_payment_id": "dcc3e785-76d3-415c-8bd7-553f17f49c4a",
"provider_id": "eg-provider",
"scheme_id": "payment_scheme",
"fee_option_id": "split_fee",
"amount_in_minor": 120000,
"currency": "GBP",
"beneficiary": {
"account": {
"type": "sort_code_account_number",
"sort_code": "234567",
"account_number": "23456789"
},
"name": "Financial Services Ltd",
},
"remitter": {
"account": {
"type": "sort_code_account_number",
"sort_code": "987654",
"account_number": "98765432"
},
"name": "Mike Smith"
},
"references": {
"type": "separate",
"beneficiary": "FinServ-1a2b3c4d",
"remitter": "FS-1000001",
}
},
"auth_flow": {
"type": "redirect",
"return_uri": "https://client.app.com/payment_return"
}
}' \
https://pay-api.truelayer.com/v2/single-immediate-payment-initiation-requests
In the response, you'll find the result.auth_flow.uri
where you need to redirect your user. The result.auth_flow.uri
value will open the payment authorisation screen.
{
"result": {
"single_immediate_payment": {
"single_immediate_payment_id": "dcc3e785-76d3-415c-8bd7-553f17f49c4a",
"status": "initiated",
"initiated_at": "2020-10-13T10:01:23.381802",
"provider_id": "eg-provider",
"scheme_id": "payment_scheme",
"fee_option_id": "split_fee",
"amount_in_minor": 120000,
"currency": "GBP",
"beneficiary": {
"account": {
"type": "sort_code_account_number",
"sort_code": "234567",
"account_number": "23456789"
},
"name": "Financial Services Ltd"
},
"remitter": {
"account": {
"type": "sort_code_account_number",
"sort_code": "987654",
"account_number": "98765432"
},
"name": "Mike Smith"
},
"references": {
"type": "separate",
"beneficiary": "FinServ-1a2b3c4d",
"remitter": "FS-1000001"
}
},
"auth_flow": {
"type": "redirect",
"uri": "https://www.eg-provider.com/authorize?token=0f9e8d7c",
"expiry": "2020-11-03T23:00:00.000Z"
}
}
}
Handle the initiation response
This feature is in private beta and is currently available to a limited number of clients. To join our private beta, contact Client Care.
The response from the /single-immediate-payment-initiation-requests
endpoint, shown above, returns the following fields:
Field | Type | Description |
---|---|---|
single_immediate_payment | SingleImmediatePaymentResponseDetails | Contains the details of the payment. This is a superset of the SingleImmediatePaymentRequestDetails object. Note this is the same object as that which will be returned on the GET /v2/single-immediate-payments/{id} endpoint. |
auth_flow | AuthFlowResponseDetails | This provides information on how to have the end user authorise the payment, and will differ in structure based on the authorisation flow. |
• SingleImmediatePaymentResponseDetails
This contains the following fields in addition to those listed in the SingleImmediatePaymentRequestDetails
section:
Field | Type | Description |
---|---|---|
initiated_at | string | The time the payment was initiated, in UTC formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ ). |
status | string | The status of the payment. For newly initiated payments, this will be initiated . |
For the structure of the AuthFlowResponseDetails
object, see our page on how to handle the payment response .
Updated 8 months ago