--- title: "Create payment link" method: POST path: "/v3/payment-links" tags: ["Payment links"] --- # Create payment link `POST /v3/payment-links` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/payment-links` - Auth: OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments`, `payment_links:create` Create a new payment link This API must be called using a backend bearer token. ## Headers - `Idempotency-Key` string, required - `Tl-Signature` string, required ## Request body - CreatePaymentLink - `type` 'single_payment', required: The type of the Payment link - `expires_at` string, datetime: The date and time the payment link will expire at. If this property isn't specified, the payment link will expire 24 hours after its creation. - `payment_configuration` PaymentDetails, required - `amount_in_minor` integer, required: A 'cent' value representing the amount, e.g. 100 == 1GBP or 100 = 1EUR - `currency` 'GBP' | 'EUR', required - `payment_method` PaymentLinkMethod, required - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the provider is to be selected from a collection - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilter: Configuration options to constrain which providers should be available during the `provider_selection` action. - `countries` CountryCode[]: Only providers from the specified countries will be returned. - `release_channel` 'general_availability' | 'public_beta' | 'private_beta': The lowest stability release stage of a provider that should be returned. Note that many EUR providers are in `public_beta` or `private_beta`. - `customer_segments` string[]: The customer segments that providers cater to that should be returned. By default, returns retail only. - `provider_ids` string[]: IDs of providers to include in those returned. - `excludes` object: Options to exclude providers included by the filters - … - `scheme_selection` union: Scheme Selection - object: Only allow providers that support instant payments. - … - object: Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable. - … - object: Indicates that the scheme is to be selected from a collection. Note: This scheme selection method is only supported by some versions of TrueLayer's mobile SDKs. Only use this option when you're sure that the end user has a version of your app on their device that supports scheme selection, or they won't be able to complete the payment. If you integrate with TrueLayer APIs directly, you must show the user a UI for scheme selection. - … - `remitter` ProviderSelectionUserSelectedRemitter: Remitter - `account_holder_name` string, required: The name of the external account holder. This field will be required if the selected provider requires it, otherwise it will be optional. pattern: `^[^\(\)]{1,80}$` - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `scheme_id` string, required: The ID of the scheme to make the payment over. - `remitter` Remitter: Remitter - `account_holder_name` string, required: The name of the external account holder. pattern: `^[^\(\)]{1,80}$` - `account_identifier` union, required: A unique account identifier for an external account. - … - `beneficiary` union, required - PaymentDestinationMerchantAccount: The identifier for a TrueLayer merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. pattern: `^[^\(\)]+$` - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - `type` 'automated', required: The type of verification. - `remitter_name` boolean: Enable verification for the remitter name. - `remitter_date_of_birth` boolean: Enable verification for the remitter date of birth. - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccount: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. Note that some providers have an 18-character upper limit for this. pattern: `^[^\(\)]+$` - `account_identifier` union, required: A unique account identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierBban: Basic bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - `reference` string, required: A reference for the payment. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `user` PaymentLinkUserCreate, required: Details of the end user who is making the payment. - `id` string: Unique ID for the User - `name` string: This is the full first and last name of your end user (not initials). one of `name`/`user_input_config.name` is required. pattern: `^[^\(\)]+$` - `email` string, email: The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822). one of `email`/`phone`/`user_input_config.email`/`user_input_config.phone`is required. - `phone` string, phone: The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`. one of `email`/`phone`/`user_input_config.email`/`user_input_config.phone`is required. - `date_of_birth` string, date: The date of birth of your end user, in `YYYY-MM-DD` format. - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `product_items` ProductItem[]: List of items associated to this link. - `name` string, required: Name of the product. - `price_in_minor` integer, required: A 'cent' value representing the price of the product, e.g. 100 == 1GBP or 100 = 1EUR - `quantity` integer, required: The product item quantity - `url` string, url: URL of the product. - `reference` string: Reference for the payment link. This reference will be shown in the link's UI. This reference won't be shared with the provider or any other third-party. - `return_uri` string, url: This URL determines where the end user will be redirected back once they successfully completed the authorization flow of a payment attempt. If no URL is provided, the end user won't be redirected anywhere, but will instead be shown TrueLayer's page notifying success. ## Response `201` Payment link - CreatedPaymentLink - `id` string, required: Unique ID for the Payment Link - `uri` string, required: Link to HPP checkout page. ## Other responses - `400`: Invalid Parameters - `401`: Unauthenticated - `403`: Forbidden - `409`: Idempotency-Key Concurrency Conflict - `422`: Idempotency-Key Reuse - `429`: Rate Limit Exceeded - `500`: Unknown Error --- [API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)