# Create Link

Used to send out a link via the Payment Links system

Set paymentLink.type to choose the flow:
- line_items (default) — a standard payment flow. Provide the products in paymentLink.lineItems.
- card_verification — performs a $0 authorization to confirm the card is valid and save it on file without charging it. These links take no lineItems, but require paymentLink.currency and a customer (a new inline customer or an existing one referenced by id).

 Integration Methods:
- Host Direct

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Endpoint: POST /paymentlinks/create
Version: 1.7.60
Security: AccessToken

## Header parameters:

  - `InterfaceVersion` (string, required)
    Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed:  $ % : ^ - ~  , ? “ ” ‘ ’ { } [ ] \ + =
    Example: "2.1"

  - `InterfaceName` (string, required)
    Refers to the name of the program or application that is sending requests to Shift4. This should be the name of the program that you purchased or created. The following special characters are not allowed:  $ % : ^ - ~ `  , ? “ ” ‘ ’ { } [ ] \ + =
    Example: "ForwardPOS"

  - `CompanyName` (string, required)
    Refers to the vendor or partner that designed and certified the interface. The information you use in this field should match what Shift4 has on file or what was agreed upon in your Integration Plan. The following special characters are not allowed:  $ % : ^ - ~ `  , ? “ ” ‘ ’ { } [ ] \ + =
    Example: "PAWS"

  - `AccessToken` (string, required)
    A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.
    Example: "EA79FB05-3AA7-4500-AF9A-73F986FF2C1D"

## Request fields (application/json):

  - `paymentLink` (any, required) — one of:
    - Line items (payment):
      - `lineItems` (array, required)
        List of line items
      - `lineItems.product` (object, required)
        Definition of a product
      - `lineItems.product.name` (string, required)
        Name of a product
      - `lineItems.product.amount` (any, required) — one of:
        Payment amount definition. Provide total for a fixed-amount link, or options and/or custom to let the customer choose the amount. total is mutually exclusive with options and custom; a customer-chosen amount link may use options, custom, or both together.
        - Fixed Total:
          - `total` (number, required)
            Payment amount (in major units, with number of allowed decimal places depending on currency)
        - Customer-chosen amount:
          - `options` (array)
            List of available pre-defined payment amounts. Allows the customer to select from a list of options for how much they want to pay. Useful whenever a merchant wants to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
          - `custom` (object)
            Possible range of custom payment amount
          - `custom.min` (number, required)
            Minimum value of custom payment amount
            Example: 10
          - `custom.max` (number, required)
            Maximum value of custom payment amount
            Example: 200
      - `lineItems.product.currencyCode` (string, required)
        currency represented as a three-letter ISO currency code
      - `lineItems.product.description` (string)
        Description of a product, shown to the customer on the hosted checkout page directly under the product name
      - `type` (string)
        The kind of flow the payment link performs.

- line_items (default) — a standard payment flow. The customer pays for the products defined in lineItems.
- card_verification — performs a $0 authorization to confirm the card is valid (a security check that a real card and cardholder are behind it) without charging it. The validated card is also saved to the customer. These links take no lineItems, but require a top-level currency and a defined customer.

When omitted, the link defaults to line_items.
        Enum: "line_items", "card_verification"
      - `currency` (string)
        Currency for the authorization, represented as a three-letter ISO currency code.

Required only for card_verification links. For line_items links the currency is taken from the line items and this field may be omitted.
      - `returnUrl` (string)
        Customer will be redirected to this URL after completing payment on paymentLink.url page.

When not provided the return URL from account setting will be used.

Some dynamic parameters will be appended to this URL. Example: {returnUrl}?status=success&checkout_session_id=chse_xxxxx
      - `collectBillingAddress` (boolean)
        If the value is true, the customer will be asked to provide the billing address.

Default: false
      - `collectShippingAddress` (boolean)
        If the value is true, the customer will be asked to provide the shipping address.

Default: false
      - `restrictions` (object)
        This object describes time boundaries and preset number of charges made with the Payment link
      - `restrictions.dates` (object)
      - `restrictions.dates.activatesAt` (string)
        Activation date of a payment link. By default, payment links are active at the moment of creation.

Max: +1 month
        Example: "2025-10-20T11:22:33.444Z"
      - `restrictions.dates.expiresAt` (string)
        Expiration date of a payment link. By default, payment links do not expire.
        Example: "2025-10-27T12:00:00.000Z"
      - `restrictions.payments` (object)
      - `restrictions.payments.limit` (integer)
        Maximum number of successful payments allowed to be done using this payment link.

Default: 1

Range: 1–999
        Example: 1
      - `notifications` (object)
        Payment Links notifications
      - `notifications.share` (object)
      - `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 taken from the customer object on the request — either supplied inline via customer.emailAddress, or read from an existing customer record referenced by customer.id.
      - `staticFields` (object)
        List of custom information (for example: hotel reservation details) in key value pair format. A maximum of 10 entries can be provided.

The key contains the title of custom information and is a maximum of 55 characters.

The value contains the text of custom information and is a maximum of 255 characters.

Examples: 
"Date of event": "12 April"
"Invoice number": "ABC2016"
      - `customFieldsTitle` (string)
        Title of custom fields section
      - `customFields` (array)
        Using custom fields, the merchant can request additional information from the customer. Each custom field will be displayed in the form as a new text field to fill out.
      - `customFields.key` (string, required)
        Identifier of custom field
        Example: "special_wishes"
      - `customFields.label` (string, required)
        Label of custom field
        Example: "Special wishes"
      - `customFields.optional` (boolean)
        If this flag is set to true, then customer doesn't have to provide any value for this custom field
      - `locale` (string)
        Language that will be used on payment page.

Default: auto = use browser language
        Enum: "auto", "en", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hr", "hu", "it", "lt", "lv", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "be"
      - `vendorReference` (string)
        Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract.
    - Card verification:
      - `type` (string, required)
        The kind of flow the payment link performs.

- line_items (default) — a standard payment flow. The customer pays for the products defined in lineItems.
- card_verification — performs a $0 authorization to confirm the card is valid (a security check that a real card and cardholder are behind it) without charging it. The validated card is also saved to the customer. These links take no lineItems, but require a top-level currency and a defined customer.

When omitted, the link defaults to line_items.
        Enum: same as `type` in "Line items (payment)" (2 values)
      - `currency` (string, required)
        Currency for the authorization, represented as a three-letter ISO currency code.

Required only for card_verification links. For line_items links the currency is taken from the line items and this field may be omitted.
      - `lineItems` (array)
        List of line items
      - `lineItems.product` (object, required)
        Definition of a product
      - `lineItems.product.name` (string, required)
        Name of a product
      - `lineItems.product.amount` (any, required) — one of:
        Payment amount definition. Provide total for a fixed-amount link, or options and/or custom to let the customer choose the amount. total is mutually exclusive with options and custom; a customer-chosen amount link may use options, custom, or both together.
        - Fixed Total:
          - `total` (number, required)
            Payment amount (in major units, with number of allowed decimal places depending on currency)
        - Customer-chosen amount:
          - `options` (array)
            List of available pre-defined payment amounts. Allows the customer to select from a list of options for how much they want to pay. Useful whenever a merchant wants to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
          - `custom` (object)
            Possible range of custom payment amount
          - `custom.min` (number, required)
            Minimum value of custom payment amount
            Example: 10
          - `custom.max` (number, required)
            Maximum value of custom payment amount
            Example: 200
      - `lineItems.product.currencyCode` (string, required)
        currency represented as a three-letter ISO currency code
      - `lineItems.product.description` (string)
        Description of a product, shown to the customer on the hosted checkout page directly under the product name
      - `returnUrl` (string)
        Customer will be redirected to this URL after completing payment on paymentLink.url page.

When not provided the return URL from account setting will be used.

Some dynamic parameters will be appended to this URL. Example: {returnUrl}?status=success&checkout_session_id=chse_xxxxx
      - `collectBillingAddress` (boolean)
        If the value is true, the customer will be asked to provide the billing address.

Default: false
      - `collectShippingAddress` (boolean)
        If the value is true, the customer will be asked to provide the shipping address.

Default: false
      - `restrictions` (object)
        This object describes time boundaries and preset number of charges made with the Payment link
      - `restrictions.dates` (object)
      - `restrictions.dates.activatesAt` (string)
        Activation date of a payment link. By default, payment links are active at the moment of creation.

Max: +1 month
        Example: "2025-10-20T11:22:33.444Z"
      - `restrictions.dates.expiresAt` (string)
        Expiration date of a payment link. By default, payment links do not expire.
        Example: "2025-10-27T12:00:00.000Z"
      - `restrictions.payments` (object)
      - `restrictions.payments.limit` (integer)
        Maximum number of successful payments allowed to be done using this payment link.

Default: 1

Range: 1–999
        Example: 1
      - `notifications` (object)
        Payment Links notifications
      - `notifications.share` (object)
      - `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 taken from the customer object on the request — either supplied inline via customer.emailAddress, or read from an existing customer record referenced by customer.id.
      - `staticFields` (object)
        List of custom information (for example: hotel reservation details) in key value pair format. A maximum of 10 entries can be provided.

The key contains the title of custom information and is a maximum of 55 characters.

The value contains the text of custom information and is a maximum of 255 characters.

Examples: 
"Date of event": "12 April"
"Invoice number": "ABC2016"
      - `customFieldsTitle` (string)
        Title of custom fields section
      - `customFields` (array)
        Using custom fields, the merchant can request additional information from the customer. Each custom field will be displayed in the form as a new text field to fill out.
      - `customFields.key` (string, required)
        Identifier of custom field
        Example: "special_wishes"
      - `customFields.label` (string, required)
        Label of custom field
        Example: "Special wishes"
      - `customFields.optional` (boolean)
        If this flag is set to true, then customer doesn't have to provide any value for this custom field
      - `locale` (string)
        Language that will be used on payment page.

Default: auto = use browser language
        Enum: same as `locale` in "Line items (payment)" (25 values)
      - `vendorReference` (string)
        Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract.

  - `customer` (any) — one of:
    - New Customer:
      - `emailAddress` (string, required)
        Email address. Required when creating an inline customer.
        Example: "john@example.com"
      - `phoneCountry` (string)
        Two-letter ISO 3166-1 alpha-2 country code used to determine the phone number's country prefix (e.g., US, GB, DE).

Required when phoneNumber does not already include the country calling code prefix (e.g., +1). When provided, the API prepends the corresponding prefix to phoneNumber and returns the full number in the response.
        Example: "US"
      - `phoneNumber` (string)
        Customer phone number. Two formats are accepted:
- With country prefix (e.g., +1 2345678901) — phoneCountry is not required.
- Without country prefix (e.g., 2345678901) — phoneCountry must be set to the appropriate alpha-2 code.
        Example: "+1 2345678901"
      - `addressLine1` (string)
        Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
      - `firstName` (string)
        Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.
      - `middleName` (string)
        Specifies a consumer’s middle name.
      - `lastName` (string)
        Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.
      - `postalCode` (string)
        Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters.

Note: This field only allows alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234
      - `addressCity` (string)
        City
        Example: "New York"
      - `addressRegion` (string)
        Region or state
        Example: "NY"
      - `addressCountry` (string)
        Country
        Example: "US"
    - Existing Customer:
      - `id` (string, required)
        Identifier of an existing customer to reuse
        Example: "cust_oM1i4j7EsIY7W5vqqF76diGw"

  - `metadata` (object)
    Key-value object for storing additional custom data.

This is never displayed to customer on the payment page.

Examples: 
"order_id": "12345"
"campaign_code": "SUMMER2025"

## Response 200 fields (application/json):

  - `result` (array)

  - `result.dateTime` (string)
    Date-time when the object was created

  - `result.paymentLink` (object)

  - `result.paymentLink.id` (string)
    Identifier of Payment Link

  - `result.paymentLink.type` (string)
    The kind of flow the payment link performs.

- line_items (default) — a standard payment flow. The customer pays for the products defined in lineItems.
- card_verification — performs a $0 authorization to confirm the card is valid (a security check that a real card and cardholder are behind it) without charging it. The validated card is also saved to the customer. These links take no lineItems, but require a top-level currency and a defined customer.

When omitted, the link defaults to line_items.
    Enum: same as `type` in "Line items (payment)" (2 values)

  - `result.paymentLink.status` (string)
    Status of a Payment link. It can be one of the following:

Value       | Description 
------------|---------------
active      | Payment link is active and functional
expired     | Payment link expired and is no longer functional
deactivated | Payment link has been deactivated by merchant
completed   | preset number of successful transactions made with this payment link has been reached, it is no longer functional
scheduled   | Payment link is yet to become active

In the [/paymentlinks/update](/apis/payments-platform-rest/openapi/payment-links/paymentslinkupdate) request this field can be used to deactivate and reactivate an existing payment link.
    Enum: "active", "expired", "deactivated", "completed", "scheduled"

  - `result.paymentLink.lastOpened` (string)
    The date the link was last opened. Omitted if the link has not been opened yet.

  - `result.paymentLink.lineItems` (array)
    List of line items

  - `result.paymentLink.lineItems.product` (object)
    Definition of a product

  - `result.paymentLink.lineItems.product.name` (string)
    Name of a product

  - `result.paymentLink.lineItems.product.description` (string)
    Description of a product, shown to the customer on the hosted checkout page directly under the product name

  - `result.paymentLink.lineItems.product.currencyCode` (string)
    currency represented as a three-letter ISO currency code

  - `result.paymentLink.lineItems.product.amount` (any) — one of:
    Payment amount definition. A fixed-amount link returns total; a customer-chosen amount link returns options, custom, or both. total is never present alongside options or custom.
    - Fixed Total:
      - `total` (number)
        Payment amount (in major units, with number of allowed decimal places depending on currency)
    - Customer-chosen amount:
      - `options` (array)
        List of available pre-defined payment amounts. Allows the customer to select from a list of options for how much they want to pay. Useful whenever a merchant wants to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
      - `custom` (object)
        Possible range of custom payment amount
      - `custom.min` (number, required)
        Minimum value of custom payment amount
        Example: 10
      - `custom.max` (number, required)
        Maximum value of custom payment amount
        Example: 200

  - `result.paymentLink.currency` (string)
    Currency for the authorization, represented as a three-letter ISO currency code.

Required only for card_verification links. For line_items links the currency is taken from the line items and this field may be omitted.

  - `result.paymentLink.url` (string)
    URL that can be used to process payment defined by this Payment Link

  - `result.paymentLink.returnUrl` (string)
    Customer will be redirected to this URL after completing payment on paymentLink.url page.

When not provided the return URL from account setting will be used.

Some dynamic parameters will be appended to this URL. Example: {returnUrl}?status=success&checkout_session_id=chse_xxxxx

  - `result.paymentLink.collectBillingAddress` (boolean)
    If the value is true, the customer will be asked to provide the billing address.

Default: false

  - `result.paymentLink.collectShippingAddress` (boolean)
    If the value is true, the customer will be asked to provide the shipping address.

Default: false

  - `result.paymentLink.restrictions` (object)
    This object describes time boundaries and preset number of charges made with the Payment link

  - `result.paymentLink.restrictions.dates` (object)

  - `result.paymentLink.restrictions.dates.activatesAt` (string)
    Activation date of a payment link. By default, payment links are active at the moment of creation.

Max: +1 month
    Example: "2025-10-20T11:22:33.444Z"

  - `result.paymentLink.restrictions.dates.expiresAt` (string)
    Expiration date of a payment link. By default, payment links do not expire.
    Example: "2025-10-27T12:00:00.000Z"

  - `result.paymentLink.restrictions.payments` (object)

  - `result.paymentLink.restrictions.payments.limit` (integer)
    Maximum number of successful payments allowed to be done using this payment link.

Default: 1

Range: 1–999
    Example: 1

  - `result.paymentLink.restrictions.payments.count` (integer)
    Number of successful payments

  - `result.paymentLink.notifications` (object)
    Payment Links notifications

  - `result.paymentLink.notifications.share` (object)

  - `result.paymentLink.notifications.share.email` (object)
    Email notification details

  - `result.paymentLink.notifications.share.email.emailAddress` (string)
    Email address
    Example: "john@example.com"

  - `result.paymentLink.notifications.share.email.status` (string)
    Email delivery status.
    Enum: "sent", "delivered", "failed"

  - `result.paymentLink.staticFields` (object)
    List of custom information (for example: hotel reservation details) in key value pair format. A maximum of 10 entries can be provided.

The key contains the title of custom information and is a maximum of 55 characters.

The value contains the text of custom information and is a maximum of 255 characters.

Examples: 
"Date of event": "12 April"
"Invoice number": "ABC2016"

  - `result.paymentLink.customFieldsTitle` (string)
    Title of custom fields section

  - `result.paymentLink.customFields` (array)
    Using custom fields, the merchant can request additional information from the customer. Each custom field will be displayed in the form as a new text field to fill out.

  - `result.paymentLink.customFields.key` (string, required)
    Identifier of custom field
    Example: "special_wishes"

  - `result.paymentLink.customFields.label` (string, required)
    Label of custom field
    Example: "Special wishes"

  - `result.paymentLink.customFields.optional` (boolean)
    If this flag is set to true, then customer doesn't have to provide any value for this custom field

  - `result.paymentLink.locale` (string)
    Language that will be used on payment page.

Default: auto = use browser language
    Enum: same as `locale` in "Line items (payment)" (25 values)

  - `result.paymentLink.vendorReference` (string)
    Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract.

  - `result.customer` (object)

  - `result.customer.id` (string)
    Identifier of the customer
    Example: "cust_oM1i4j7EsIY7W5vqqF76diGw"

  - `result.customer.emailAddress` (string)
    Email
    Example: "john@example.com"

  - `result.customer.phoneCountry` (string)
    Two-letter ISO 3166-1 alpha-2 country code of the phone number's country (e.g., US, GB, DE). Present when the customer was created with phoneCountry set.
    Example: "US"

  - `result.customer.phoneNumber` (string)
    Phone number. When phoneCountry was provided on creation, the number is returned with the corresponding country calling code prepended.
    Example: "+1 2345678901"

  - `result.customer.addressLine1` (string)
    Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.

  - `result.customer.firstName` (string)
    Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.

  - `result.customer.middleName` (string)
    Specifies a consumer’s middle name.

  - `result.customer.lastName` (string)
    Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.

  - `result.customer.postalCode` (string)
    Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters.

Note: This field only allows alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234

  - `result.customer.addressCity` (string)
    City
    Example: "New York"

  - `result.customer.addressRegion` (string)
    Region or state
    Example: "NY"

  - `result.customer.addressCountry` (string)
    Country
    Example: "US"

  - `result.metadata` (object)
    Key-value object for storing additional custom data.

This is never displayed to customer on the payment page.

Examples: 
"order_id": "12345"
"campaign_code": "SUMMER2025"

## Response 400 fields (application/json):

  - `result` (array)
    Example: [{"error":{"primaryCode":9842,"secondaryCode":0,"shortText":"NOT IN CARDRANGE","longText":"Card type not recognized"},"lighthouse":{"data":"eyJwYXltZW50SWQiOiI4NWM0MWNhNy01NzVjLTQzNGUtODIyZi0xYzZlOTE0ZDAzODYiLCJyZW1haW5pbmdBbW91bnQiOjB9"},"server":{"name":"U2API01CE"}}]

  - `result.error` (object)

  - `result.error.code` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.

Note: This is currently only supported for European merchant processing.

  - `result.error.severity` (string)
    Severity level of the error.

| Severity | Description                                                       |
| -------- | ----------------------------------------------------------------  |
| Info     | Action not required - Data input/formatting is incorrect          |
| Error    | Action may be required - Communication, timeout or network issue  |
| Alert    | Action required - System issue                                    |
    Enum: "Info", "Error", "Alert"

  - `result.error.shortText` (string)
    Abbreviated error message that is always returned if an error condition exists

  - `result.error.longText` (string)
    Extended error message that is returned if an error condition exists.

  - `result.error.primaryCode` (integer)
    Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details.

  - `result.error.secondaryCode` (integer)
    This code supplements the code specified in the error.primaryCode field to provide additional information about the error that occurred.

  - `result.lighthouse` (object)

  - `result.lighthouse.data` (string)
    Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.

  - `result.server` (object)

  - `result.server.name` (string)
    The name of the server that processed the request.

## Response 504 fields (application/json):

  - `result` (array)

  - `result.error` (object)

  - `result.lighthouse` (object)

  - `result.lighthouse.data` (string)
    Base64 encoded JSON formatted data that will be returned from Lighthouse to be passed back to SkyTab. This data will contain variable information.

  - `result.server` (object)