Initiate a payment [Payments V2]

Get an access token and initiate your payment.

Get an access token

To get an access token, you need your client ID and client secret for the environment you are using (live or sandbox). The client ID can be found in the settings page of your Console. If you don't have your client_secret, you can also generate a new one.

Use our authentication server to get an access token using the client_credentials grant type. You'll need the access_token to make requests to different payments endpoints.

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

You receive a response as below:

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Initiate a payment

Create a payment initiation request with information from your user.

🚧

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:

FieldTypeMandatoryDescription
single_immediate_paymentSingleImmediatePaymentRequestDetailsMandatorySpecifies the details of the payment to be created.

Possible values are in the table below.
auth_flowAuthFlowRequestDetailsMandatorySpecifies how the payment should be authorised.

Possible values are in the fifth table below.
webhook_uristringOptionalAn address to which payment webhooks with the status of the payment should be sent. Has to be https.

SingleImmediatePaymentRequestDetails

FieldTypeMandatoryDescription
single_immediate_payment_iduuidMandatoryThe 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_minornumberMandatoryThe amount, specified in terms of the fractional monetary unit of the payment currency, to be paid.
currencystringMandatoryThe ISO 4217 code of the currency for the payment.
provider_idstringMandatoryThe id of the provider, as given on our /providers endpoint.
scheme_idstringMandatoryThe 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_idstringConditionalThe 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).
beneficiaryParticipantDetailsMandatoryThe details of the beneficiary receiving the payment.

Possible values are in the table below.
remitterParticipantDetailsConditionalThe details of the remitter sending the payment.

Possible values are in the table below.
referencesReferencesDetailsMandatoryThe details of the reference, or references, for the payment.

Possible values are in the third table below.

ParticipantDetails

FieldTypeMandatoryDescription
accountAccountIdentifierDetailsMandatoryThe details of the account owned by the participant.

Possible values are in the table below.
namestringConditionalThe name on the participant's account.

AccountIdentifierDetails

FieldTypeMandatoryDescription
typestringMandatoryThe 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_codestringMandatory if type is sort_code_account_number. Invalid otherwise.6 digit sort code (no spaces or dashes).
account_numberstringMandatory if type is sort_code_account_number. Invalid otherwise.8 digit account number.
ibanstringMandatory 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).
bbanstringMandatory 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.
nrbstringMandatory 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

FieldTypeMandatoryDescription
typestringMandatoryThe 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.
referencestringMandatory if type is single. Invalid otherwise.The reference to appear on the beneficiary's and remitter's statements.
beneficiarystringMandatory if type is separate. Invalid otherwise.The reference to appear on the beneficiary's statement.
remitterstringMandatory if type is separate. Invalid otherwise.The reference to appear on the remitter's statement.

AuthFlowRequestDetails

FieldTypeMandatoryDescription
typestringMandatoryThe type of authorisation flow. Must be redirect or embedded. Providers requiring additional authorisation flows may be available in future.
return_uristringMandatory 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_addressstringConditional if type is redirect. Invalid otherwise.The IP address of the end user.
data_access_tokenstringOptional 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_inputsdictionary<string, string>ConditionalA 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 opens 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:

FieldTypeDescription
single_immediate_paymentSingleImmediatePaymentResponseDetailsContains 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_flowAuthFlowResponseDetailsThis 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:

FieldTypeDescription
initiated_atstringThe time the payment was initiated, in UTC formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ).
statusstringThe status of the payment. For newly initiated payments, this will be initiated.

For the structure of the AuthFlowResponseDetails object, see step 4 about how to how to handle the payment response.