Create a payment link
Learn how to create a payment link with the TrueLayer Payments API v3.
Payment links are in private beta
To enable this feature, please contact us.
Prerequisites
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 /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 URL that the end user is redirected to after they successfully complete the payment authorisation flow. If you don't provide a URL, 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_minorfor allproduct_itemsdoes not have to have a total that is the same aspayment_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_atpasses. - 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.
Webhook interactions with payment links
When a payment is created via a payment link, you receive a new webhook type with the payment link id and payment id within the payload.
You must register for webhooks for that payment id to follow along with the existing webhooks for successful or failed payments. If your user hasn't made the payment by the time the payment link expires, you receive a webhook that notifies you.
If a payment has been created for the payment link you do not receive a specific payment link-related webhook. As a payment is created at that point, check the webhooks created for that payment instead.
Updated 22 days ago