# Create a payment link

Creates a new payment link. Every new payment link is active by default.

Endpoint: POST /payment-links
Version: 1.0.0
Security: BasicAuth

## Request fields (application/json):

  - `lineItems` (array, required)
    List of items to be paid for through the payment link.

  - `lineItems.product` (object)
    Item being paid for. Provide `id` to reference an existing product, otherwise the details given here are used to create a new product, which also becomes available via the `/products` endpoint. For a subscription item, provide `plan` instead.

  - `lineItems.product.id` (string)
    Identifier of an existing product.
    Example: product_kV8XmQzR3TfBnLpAyHcDe2Wj

  - `lineItems.product.name` (string)
    Product name.
    Example: Premium subscription

  - `lineItems.product.description` (string)
    Description of the product, shown to the customer on the hosted payment page directly under the product name.
    Example: Annual access to all premium features

  - `lineItems.product.amount` (any)
    Payment amount definition. Provide an integer for a fixed-amount item, or an object with `options` and/or `custom` to let the customer choose the amount. A fixed amount is mutually exclusive with `options` and `custom`; a customer-chosen amount may use `options`, `custom`, or both together.

  - `lineItems.product.amount.options` (array)
    List of available pre-defined payment amounts, in minor units of a given currency. Allows the customer to select from a list of options for how much they want to pay. Useful whenever you want to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
    Example: [1000,2500,5000]

  - `lineItems.product.amount.custom` (object)
    Possible range of a custom payment amount, letting the customer enter any value between `min` and `max`.

  - `lineItems.product.amount.custom.min` (integer)
    Minimum value of the custom payment amount, in minor units of a given currency.
    Example: 500

  - `lineItems.product.amount.custom.max` (integer)
    Maximum value of the custom payment amount, in minor units of a given currency.
    Example: 100000

  - `lineItems.product.currency` (string)
    Three-letter ISO currency code.
    Example: USD

  - `lineItems.product.plan` (string)
    Identifier of the plan that should be charged. Set on subscription items instead of `amount` and `currency`.
    Example: plan_bLu3vzO8yhAFhbxFEadm6HUV

  - `lineItems.product.taxes` (array)
    List of taxes applied to the product.

  - `lineItems.product.taxes.id` (string)
    Identifier of an existing tax entry.
    Example: tax_kPzT0OjFR9AwGiWtSvKMcHzP

  - `lineItems.product.taxes.name` (string)
    Tax name.
    Example: VAT

  - `lineItems.product.taxes.value` (number)
    Tax percentage.
    Example: 23

  - `staticFields` (array)
    List of static fields shown as additional information on the payment page. Static fields are informational only and cannot be edited by the customer.

  - `staticFields.key` (string)
    Title of the custom information.
    Example: Order no.

  - `staticFields.value` (string)
    Text of the custom information, shown under the specified key.
    Example: #21378

  - `collectBillingAddress` (boolean)
    Whether the customer will be asked to provide the billing address.
    Example: true

  - `collectShippingAddress` (boolean)
    Whether the customer will be asked to provide the shipping address.
    Example: false

  - `locale` (string)
    Two-letter abbreviation of the language that will be used on the payment page. If not provided, the customer's browser language is used.
    Enum: "en", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hr", "hu", "it", "lt", "lv", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "be"

  - `returnUrl` (string)
    URL to which the customer is redirected after completing the payment using the payment link. Must be an HTTP or HTTPS URL of up to 2048 characters. If not provided, the return URL configured in Checkout Settings is used.
    Example: https://merchant.example.com/payment/return

  - `restrictions` (object)
    Time boundaries and the preset number of charges that can be made with the payment link.

  - `restrictions.charges` (object)
    Limits the number of successful attempts to use the payment link.

  - `restrictions.charges.limit` (integer)
    Maximum number of successful charges allowed to be made using this payment link. When not set, the number of charges is not limited. For a `card_verification` link this field is required and must be set to `1`, as such a link can only be used once.
    Example: 20

  - `restrictions.dates` (object)
    Activation and expiration dates.

  - `restrictions.dates.activatesAt` (integer)
    Unix timestamp (seconds) at which the payment link becomes active. By default, payment links are active from the moment of creation.
    Example: 1746021690

  - `restrictions.dates.expiresAt` (integer)
    Unix timestamp (seconds) at which the payment link expires. Must be in the future and no more than 5 years from now, and must be later than `activatesAt`. By default, payment links do not expire.
    Example: 1777557690

  - `customer` (string)
    Identifier of the customer that will be associated with the charge or subscription created through the payment link.
    Example: cust_AoR0wvgntQWRUYMdZNLYMz5R

  - `allowSavedCards` (boolean)
    Whether the payment form should display the option to save the customer's card details for future transactions. A customer must be assigned to use this option.
    Example: true

  - `notifications` (object)
    Payment link notifications.

  - `notifications.share` (object)
    Controls automatically sending the payment link to the customer.

  - `notifications.share.sms` (boolean)
    Whether the payment link should be sent automatically as an SMS to the assigned customer. The customer must have a phone number defined. SMS notifications are available for selected business models only — contact [devsupport@shift4.com](mailto:devsupport@shift4.com) to find out more.
    Example: true

  - `notifications.share.email` (boolean)
    If this flag is set to `true`, the payment link is automatically sent by email to the customer. The email address is read from the customer record referenced by `customer`, which must therefore be set and must have an email address defined.
    Example: true

  - `customFieldsTitle` (string)
    Title of the custom fields section.
    Example: Additional information

  - `customFields` (array)
    List of custom fields used to request additional information from the customer. Each custom field is displayed in the form as a new text field to fill out.

  - `customFields.key` (string)
    Identifier of the custom field.
    Example: engraving

  - `customFields.label` (string)
    Label of the field shown on the Checkout form.
    Example: Engraving text

  - `customFields.value` (string)
    Value provided by the customer. Only present once the customer has filled in the field.
    Example: Happy Birthday

  - `customFields.optional` (boolean)
    If this flag is set to `true`, the customer does not have to provide a value for this custom field.
    Example: true

  - `action` (string)
    Action performed when the customer opens the payment link.
    Enum: "payment", "card_verification"

  - `currency` (string)
    Three-letter ISO currency code. Required for the `card_verification` action — for a regular payment, the currency from `lineItems` is used.
    Example: USD

  - `vendorReference` (string)
    Merchant-side reference (for example, an invoice number).
    Example: custom_vendor_reference

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier of the payment link.
    Example: link_8v6pz2FEOvlDA80wOGhUhP8N

  - `created` (integer)
    Unix timestamp (seconds) when the payment link was created.
    Example: 1746021690

  - `status` (string)
    Current status of the payment link. Use the [deactivate](/docs/api/shift4-gateway/payment-links/deactivatepaymentlink) and [reactivate](/docs/api/shift4-gateway/payment-links/reactivatepaymentlink) endpoints to change it.
    Enum: "active", "scheduled", "expired", "deactivated", "completed"

  - `url` (string)
    URL that can be used to process the payment defined by this payment link.
    Example: https://pay.shift4.com/link_8v6pz2FEOvlDA80wOGhUhP8N

  - `lastOpened` (integer)
    Unix timestamp (seconds) when the payment link was last opened. If it has not been opened yet, the value is `null`.
    Example: 1746025976

  - `lineItems` (array)
    List of items to be paid for through the payment link.

  - `lineItems.product` (object)
    Item being paid for. Provide `id` to reference an existing product, otherwise the details given here are used to create a new product, which also becomes available via the `/products` endpoint. For a subscription item, provide `plan` instead.

  - `lineItems.product.id` (string)
    Identifier of an existing product.
    Example: product_kV8XmQzR3TfBnLpAyHcDe2Wj

  - `lineItems.product.name` (string)
    Product name.
    Example: Premium subscription

  - `lineItems.product.description` (string)
    Description of the product, shown to the customer on the hosted payment page directly under the product name.
    Example: Annual access to all premium features

  - `lineItems.product.amount` (any)
    Payment amount definition. Provide an integer for a fixed-amount item, or an object with `options` and/or `custom` to let the customer choose the amount. A fixed amount is mutually exclusive with `options` and `custom`; a customer-chosen amount may use `options`, `custom`, or both together.

  - `lineItems.product.amount.options` (array)
    List of available pre-defined payment amounts, in minor units of a given currency. Allows the customer to select from a list of options for how much they want to pay. Useful whenever you want to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
    Example: [1000,2500,5000]

  - `lineItems.product.amount.custom` (object)
    Possible range of a custom payment amount, letting the customer enter any value between `min` and `max`.

  - `lineItems.product.amount.custom.min` (integer)
    Minimum value of the custom payment amount, in minor units of a given currency.
    Example: 500

  - `lineItems.product.amount.custom.max` (integer)
    Maximum value of the custom payment amount, in minor units of a given currency.
    Example: 100000

  - `lineItems.product.currency` (string)
    Three-letter ISO currency code.
    Example: USD

  - `lineItems.product.plan` (string)
    Identifier of the plan that should be charged. Set on subscription items instead of `amount` and `currency`.
    Example: plan_bLu3vzO8yhAFhbxFEadm6HUV

  - `lineItems.product.taxes` (array)
    List of taxes applied to the product.

  - `lineItems.product.taxes.id` (string)
    Identifier of an existing tax entry.
    Example: tax_kPzT0OjFR9AwGiWtSvKMcHzP

  - `lineItems.product.taxes.name` (string)
    Tax name.
    Example: VAT

  - `lineItems.product.taxes.value` (number)
    Tax percentage.
    Example: 23

  - `staticFields` (array)
    List of static fields shown as additional information on the payment page. Static fields are informational only and cannot be edited by the customer.

  - `staticFields.key` (string)
    Title of the custom information.
    Example: Order no.

  - `staticFields.value` (string)
    Text of the custom information, shown under the specified key.
    Example: #21378

  - `collectBillingAddress` (boolean)
    Whether the customer will be asked to provide the billing address.
    Example: true

  - `collectShippingAddress` (boolean)
    Whether the customer will be asked to provide the shipping address.
    Example: false

  - `locale` (string)
    Two-letter abbreviation of the language that will be used on the payment page. If not provided, the customer's browser language is used.
    Enum: "en", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hr", "hu", "it", "lt", "lv", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "be"

  - `returnUrl` (string)
    URL to which the customer is redirected after completing the payment using the payment link. Must be an HTTP or HTTPS URL of up to 2048 characters. If not provided, the return URL configured in Checkout Settings is used; a `returnUrl` set on the payment link overrides that default.
After the checkout flow is completed, the `status` and `checkout_session_id` query parameters are appended to the redirect URL.
    Example: https://merchant.example.com/payment/return

  - `restrictions` (object)
    Time boundaries and the preset number of charges that can be made with the payment link.

  - `restrictions.charges` (object)
    Limits the number of successful attempts to use the payment link, and reports how many successful attempts there were.

  - `restrictions.charges.limit` (integer)
    Maximum number of successful charges allowed to be made using this payment link. When not set, the number of charges is not limited. For a `card_verification` link this field is required and must be set to `1`, as such a link can only be used once.
    Example: 20

  - `restrictions.charges.count` (integer)
    Number of successful charges already made with the payment link. Not writable.
    Example: 0

  - `restrictions.dates` (object)
    Activation and expiration dates.

  - `restrictions.dates.activatesAt` (integer)
    Unix timestamp (seconds) at which the payment link becomes active. By default, payment links are active from the moment of creation.
    Example: 1746021690

  - `restrictions.dates.expiresAt` (integer)
    Unix timestamp (seconds) at which the payment link expires. Must be in the future and no more than 5 years from now, and must be later than `activatesAt`. By default, payment links do not expire.
    Example: 1777557690

  - `customer` (string)
    Identifier of the customer associated with the charge or subscription created through the payment link.
    Example: cust_AoR0wvgntQWRUYMdZNLYMz5R

  - `allowSavedCards` (boolean)
    Whether the payment form should display the option to save the customer's card details for future transactions. A customer must be assigned to use this option.
    Example: true

  - `action` (string)
    The kind of flow the payment link performs. When omitted, the link defaults to `payment`.
    Enum: "payment", "card_verification"

  - `currency` (string)
    Currency for the authorization, represented as a three-letter ISO currency code.
**Required only for `card_verification` links.** For `payment` links the currency is taken from the line items and this field may be omitted.
    Example: USD

  - `notifications` (object)
    Payment link notifications.

  - `notifications.share` (object)
    Controls automatically sending the payment link to the customer.

  - `notifications.share.sms` (boolean)
    Whether the payment link should be sent automatically as an SMS to the assigned customer. The customer must have a phone number defined. SMS notifications are available for selected business models only — contact [devsupport@shift4.com](mailto:devsupport@shift4.com) to find out more.
    Example: true

  - `notifications.share.email` (boolean)
    If this flag is set to `true`, the payment link is automatically sent by email to the customer. The email address is read from the customer record referenced by `customer`, which must therefore be set and must have an email address defined.
    Example: true

  - `customFieldsTitle` (string)
    Title of the custom fields section.
    Example: Additional information

  - `customFields` (array)
    List of custom fields used to request additional information from the customer. Each custom field is displayed in the form as a new text field to fill out. Values entered by the customer are available on the checkout session associated with the charge.

  - `customFields.key` (string)
    Identifier of the custom field.
    Example: engraving

  - `customFields.label` (string)
    Label of the field shown on the Checkout form.
    Example: Engraving text

  - `customFields.value` (string)
    Value provided by the customer. Only present once the customer has filled in the field.
    Example: Happy Birthday

  - `customFields.optional` (boolean)
    If this flag is set to `true`, the customer does not have to provide a value for this custom field.
    Example: true

  - `vendorReference` (string)
    Merchant-defined descriptor related to the payment link (for example, an invoice number). This field is reportable on the merchant portal and settlement extract.
    Example: custom_vendor_reference

## Response 400 fields (application/json):

  - `error` (object)

  - `error.type` (string)
    Error type
    Enum: "invalid_request", "card_error", "gateway_error"

  - `error.code` (string)
    Machine-readable error code
    Example: invalid_number

  - `error.message` (string)
    Human-readable error message
    Example: Requested object does not exist

  - `error.chargeId` (string)
    ID of the charge associated with this error (if applicable)
    Example: char_ORVCrwOrTkGsDwM3H50OIW7Q