Create a payment link

Learn how to create a payment link with the TrueLayer Payments API v3.


To create a payment link, you need:

Create a payment link

To create a payment link, you need to make a POST request to the /v3/payment-links endpoint. This should include an idempotency key, and be signed with a Tl-signature header.

In the request, use these parameters:

typestringYesThe type of payment that the link creates. Can only be "single_payment".
(RFC-3339 format)
NoThe date and time the payment link expires at.

If you don't provide this parameter, the payment link expires 24 hours after creation by default.
payment_configurationobjectYesThe payment the link creates when accessed. This follows the same structure as the create payment request in Payments v3, except:

This configuration only supports the bank_transfer payment method, and does not support a data_access_token.
product_itemsarray of objectsNoA list of the items that the user pays for through the payment link.
referencestringNoA reference for the payment link. This is shown in the UI the user accesses through the link and isn't shared with the provider.
return_uristring NoThe URI that the end user is redirected to after they successfully complete the payment authorisation flow.

If you don't provide a URI, the end user is not redirected and is shown a success screen.

See below for an example request:

  "type": "single_payment",
  "expires_at": "2023-01-22T07:30:53.527Z",
  "payment_configuration": {
    "amount_in_minor": 1,
    "currency": "GBP",
    "payment_method": {
      "type": "bank_transfer",
      "provider_selection": {
        "type": "user_selected",
        "filter": {
          "countries": [
          "release_channel": "general_availability",
          "customer_segments": [
          "provider_ids": [
          "excludes": {
            "provider_ids": [
        "scheme_selection": {
          "type": "instant_only",
          "allow_remitter_fee": false
      "beneficiary": {
        "type": "merchant_account",
        "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
        "account_holder_name": "Ben Eficiary",
        "reference": "payment-ref"
    "user": {
      "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
      "name": "Remi Terr",
      "email": "[email protected]",
      "phone": "+447777777777",
      "date_of_birth": "1990-01-31",
      "address": {
        "address_line1": "1 Hardwick St",
        "address_line2": "Clerkenwell",
        "city": "London",
        "state": "London",
        "zip": "EC1R 4RB",
        "country_code": "GB"
    "metadata": {
      "prop1": "value1",
      "prop2": "value2"
  "product_items": [
      "name": "Oak Table",
      "price_in_minor": 1,
      "quantity": 1,
      "url": ""
  "reference": "TABLES_R_US_LINK_42",
  "return_uri": ""

If successful, the response contains an id for the payment link and the link itself, in the form of a URI.

  "id": "aKiW35RWSyF",
  "uri": ""

Products on your checkout page

When you create a payment link, you can provide an optional array of product_items. These display on the checkout page of the payment link, giving the user a preview of what they're paying for.

There are several objects you can configure for each item in the product_items array:

Object within product_itemsTypeRequired?Description
nameStringYesThe product name that displays on the checkout screen.

Supports special characters and has a character limit of 150 characters.
price_in_minorNumberYesThe value of the product, which displays to the right of the product name on the checkout screen.

On the checkout page, the price_in_minor for each product_item is multiplied by its quantity.
quantityNumberYesThe quantity of the product, which displays beneath the product name if it has a quantity of two or more.

Each quantity object must have a value of one or more or you receive an error.
urlstringNoThe link for each product. If provided, the product name on the checkout page is linked to this URL, so the customer can check what the product is.


The sum of the price_in_minor for all product_items does not have to have a total that is the same as payment_configuration.price_in_minor.

Payment link lifecycle

A payment link remains valid even if a user's initial payment fails, enabling the user to try and make the payment again.

The two only things that make a payment link invalid are:

  • If the payment link expires after the time specified in expires_at passes.
  • The payment in the payment link succeeds.
A flow diagram explaining the lifecycle of a payment link.

A flow diagram explaining the lifecycle of a payment link.

You can set the expires_at property to a date and time in RFC-3339 format. This specifies how long your user can pay with your link before it expires. If you don't set a value for expires_at, the payment link will be usable for 24 hours, but you can specify a longer expiration period if you prefer.