Initiate a payment [Payments V2]

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 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:

Field	Type	Mandatory	Description
`single_immediate_payment`	`SingleImmediatePaymentRequestDetails`	Mandatory	Specifies the details of the payment to be created. Possible values are in the table below.
`auth_flow`	`AuthFlowRequestDetails`	Mandatory	Specifies how the payment should be authorised. Possible values are in the fifth table below.
`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. Possible values are in the table below.
`remitter`	`ParticipantDetails`	Conditional	The details of the remitter sending the payment. Possible values are in the table below.
`references`	`ReferencesDetails`	Mandatory	The details of the reference, or references, for the payment. Possible values are in the third table below.

`ParticipantDetails`

Field	Type	Mandatory	Description
`account`	`AccountIdentifierDetails`	Mandatory	The details of the account owned by the participant. Possible values are in the table below.
`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 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:

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 step 4 about how to how to handle the payment response.