Create a payment link

Prerequisites

To create a payment link, you need:

An idempotency key
A Tl-Signature header

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:

Parameter	Type	Required?	Description
`type`	string	Yes	The type of payment that the link creates. Can only be `"single_payment"`.
`expires_at`	string (RFC-3339 format)	No	The 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_configuration`	object	Yes	The 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_items`	array of objects	No	A list of the items that the user pays for through the payment link.
`reference`	string	No	A 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_uri`	string	No	The 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": [
            "GB"
          ],
          "release_channel": "general_availability",
          "customer_segments": [
            "retail"
          ],
          "provider_ids": [
            "mock-payments-gb-redirect"
          ],
          "excludes": {
            "provider_ids": [
              "ob-exclude-this-bank"
            ]
          }
        },
        "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": "https://tablesrus.com/oak-table-42"
    }
  ],
  "reference": "TABLES_R_US_LINK_42",
  "return_uri": "https://tablesrus.com/thank-you-for-your-order"
}

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

{
  "id": "aKiW35RWSyF",
  "uri": "https://payment.truelayer.com/checkout/aKiW35RWSyF"
}

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_items`	Type	Required?	Description
`name`	String	Yes	The product name that displays on the checkout screen. Supports special characters and has a character limit of 150 characters.
`price_in_minor`	Number	Yes	The 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`.
`quantity`	Number	Yes	The 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.
`url`	string	No	The 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.

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.