--- title: "Create Link" method: POST path: "/paymentlinks/create" tags: ["Payment Links"] --- # Create Link `POST /paymentlinks/create` 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](/guides/quickstart#integration-methods) and [URLs Section](/guides/quickstart#urls) sections of the Development Quick Start guide for details regarding each processing option. ## Headers - `InterfaceVersion` string, required - `InterfaceName` string, required - `CompanyName` string, required - `AccessToken` string, uuid, required ## Request body - object - `paymentLink` union, required — Configuration of the payment link. Required fields depend on `type`: - `line_items` (default) — `lineItems` is required; `currency` is taken from the line items. - `card_verification` — `currency` is required and `lineItems` must be omitted. A `customer` must also be supplied at the top level of the request. - object - `id` string — Identifier of Payment Link - `type` 'line_items' — 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`. - `lineItems` object[], required — List of line items - `product` object, required — Definition of a product - `name` string, required — Name of a product - `description` string — Description of a product, shown to the customer on the hosted checkout page directly under the product name - `currencyCode` string, required — currency represented as a three-letter ISO currency code - `amount` union, required — 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. - object - … - object - … - `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` PaymentLinkRestrictions — This object describes time boundaries and preset number of charges made with the Payment link - `dates` object - `activatesAt` string, ISO 8601 — Activation date of a payment link. By default, payment links are active at the moment of creation. Max: +1 month - `expiresAt` string, ISO 8601 — Expiration date of a payment link. By default, payment links do not expire. - `payments` object - `limit` integer — Maximum number of successful payments allowed to be done using this payment link. Default: 1 Range: 1–999 - `count` integer — Number of successful payments - `notifications` PaymentLinkNotificationsRequest — Payment Links notifications - `share` object - `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` PaymentLinkStaticFields — 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` object[] — 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. - `key` string, required — Identifier of custom field - `label` string, required — Label of custom field - `optional` boolean — If this flag is set to `true`, then customer doesn't have to provide any value for this custom field - `locale` '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' — Language that will be used on payment page. Default: `auto` = use browser language - `vendorReference` string — Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract. - object - `id` string — Identifier of Payment Link - `type` 'card_verification', 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`. - `lineItems` object[] — List of line items - `product` object, required — Definition of a product - `name` string, required — Name of a product - `description` string — Description of a product, shown to the customer on the hosted checkout page directly under the product name - `currencyCode` string, required — currency represented as a three-letter ISO currency code - `amount` union, required — 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. - object - … - object - … - `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. - `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` PaymentLinkRestrictions — This object describes time boundaries and preset number of charges made with the Payment link - `dates` object - `activatesAt` string, ISO 8601 — Activation date of a payment link. By default, payment links are active at the moment of creation. Max: +1 month - `expiresAt` string, ISO 8601 — Expiration date of a payment link. By default, payment links do not expire. - `payments` object - `limit` integer — Maximum number of successful payments allowed to be done using this payment link. Default: 1 Range: 1–999 - `count` integer — Number of successful payments - `notifications` PaymentLinkNotificationsRequest — Payment Links notifications - `share` object - `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` PaymentLinkStaticFields — 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` object[] — 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. - `key` string, required — Identifier of custom field - `label` string, required — Label of custom field - `optional` boolean — If this flag is set to `true`, then customer doesn't have to provide any value for this custom field - `locale` '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' — Language that will be used on payment page. Default: `auto` = use browser language - `vendorReference` string — Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract. - `customer` union - object - `emailAddress` string, required — Email address. Required when creating an inline customer. - `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. - `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. - `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 - `addressRegion` string — Region or state - `addressCountry` string — Country - object - `id` string, required — Identifier of an existing customer to reuse - `metadata` PaymentLinksMetadata — 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` Request was processed - object - `result` object[] - `dateTime` string, ISO 8601 — Date-time when the object was created - `paymentLink` PaymentLinkResponse - `id` string — Identifier of Payment Link - `type` 'line_items' | 'card_verification' — 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`. - `status` 'active' | 'expired' | 'deactivated' | 'completed' | 'scheduled' — 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. - `lastOpened` string, ISO 8601 — The date the link was last opened. Omitted if the link has not been opened yet. - `lineItems` object[] — List of line items - `product` object — Definition of a product - `name` string — Name of a product - `description` string — Description of a product, shown to the customer on the hosted checkout page directly under the product name - `currencyCode` string — currency represented as a three-letter ISO currency code - `amount` union — 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`. - object - … - object - … - `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. - `url` string — URL that can be used to process payment defined by this Payment Link - `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` PaymentLinkRestrictions — This object describes time boundaries and preset number of charges made with the Payment link - `dates` object - `activatesAt` string, ISO 8601 — Activation date of a payment link. By default, payment links are active at the moment of creation. Max: +1 month - `expiresAt` string, ISO 8601 — Expiration date of a payment link. By default, payment links do not expire. - `payments` object - `limit` integer — Maximum number of successful payments allowed to be done using this payment link. Default: 1 Range: 1–999 - `count` integer — Number of successful payments - `notifications` PaymentLinkNotificationsResponse — Payment Links notifications - `share` object - `email` object — Email notification details - `emailAddress` string — Email address - `status` 'sent' | 'delivered' | 'failed' — Email delivery status. - `staticFields` PaymentLinkStaticFields — 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` object[] — 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. - `key` string, required — Identifier of custom field - `label` string, required — Label of custom field - `optional` boolean — If this flag is set to `true`, then customer doesn't have to provide any value for this custom field - `locale` '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' — Language that will be used on payment page. Default: `auto` = use browser language - `vendorReference` string — Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract. - `customer` PaymentLinksCustomerResponse - `id` string — Identifier of the customer - `emailAddress` string — Email - `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. - `phoneNumber` string — Phone number. When `phoneCountry` was provided on creation, the number is returned with the corresponding country calling code prepended. - `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 - `addressRegion` string — Region or state - `addressCountry` string — Country - `metadata` PaymentLinksMetadata — 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"` ## Other responses - `400` — Error - `504` — Timeout --- [API](https://skmtc.dev/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.dev/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/revisions/2f85c87cc9e5/schema)