--- title: "Create a Payment Link" method: POST path: "/payment-links" tags: ["Payment Links"] --- # Create a Payment Link `POST /payment-links` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/payment-links` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a Payment Link and pass through all the payment information, like the amount, currency, country and reference. ## Request body - PaymentLinksRequest - `amount` integer, required: The payment amount. The exact format depends on the currency. - `currency` string, required: The three-letter ISO currency code of the payment.
The `currency` and `billing.address.country` fields determine which payment methods are shown on the payment page. - `payment_type` 'Regular' | 'Recurring': This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order) - `authorization_type` 'Final' | 'Estimated': The authorization type. - `payment_plan` PaymentSessionPaymentPlanRecurring: The information to process a recurring payment request. To be used when the payment_type is Recurring. - `amount_variability` 'Fixed' | 'Variable': Specifies whether the amount is fixed or variable for each recurrence. - `days_between_payments` integer: Indicates the minimum number of days between payments. - `total_number_of_payments` integer: Indicates the agreed total number of payments. - `current_payment_number` integer: The number of the current installment payment. - `expiry` string: The date after which no further payments will be performed, in the format YYYYMMDD. - `name` string: The name of the payment plan. Required when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label. - `start_date` string: The date on which the first payment will be taken, in `YYYYMMDD` format. Required when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`). - `amount` integer: The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount). Required when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`). - `payment_ip` string, ipv4 - `billing_descriptor` object: An optional description that is displayed on the customer's statement identifying a purchase - `name` string, required: A dynamic description of the change - `city` string, required: The city from which the charge originated - `reference` string: The reference shown on the statement. Required for payouts to bank accounts. - `reference` string: A reference you can use to identify the payment. For example, an order number. - For Amex payments, this must be at most 30 characters. - For Benefit payments, the reference must be a unique alphanumeric value. - For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit. - `description` string: A description of the payment. - `display_name` string: The merchant name to display to customers on the checkout page. - `processing_channel_id` string: The processing channel to use for the payment.

This field is required if you have more than one processing channel associated with your API key. - `amount_allocations` object[]: The sub-entities that the payment is being processed on behalf of - `id` string, required: The id of the sub-entity. - `amount` integer, required: The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount. The amount must be provided in the minor currency unit. - `reference` string: A reference you can later use to identify this split, such as an order number. - `commission` object: Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount. Commission = (`amount` * `commission.percentage`) + `commission.amount` - `amount` integer: Optional fixed amount of commission to collect. The amount must be provided in the minor currency unit. - `percentage` number: Optional percentage of commission to collect. Supports up to 8 decimal places. - `expires_in` integer: The time for which the link remains valid, in seconds. - `customer` object: The customer's details - `email` string, email: The customer's email address. - `name` string: The customer's name. This will only set the name for new customers. - `phone` PaymentInterfacesPhoneNumber: A phone number - `country_code` string: The international country calling code. - `number` string: The phone number. - `summary` PaymentInterfacesCustomerSummary: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara` - `registration_date` string, date: The date the customer registered. - `first_transaction_date` string, date: The date of the customer's first transaction. - `last_payment_date` string, date: The date of the customer's last payment. - `total_order_count` integer: The total number of orders made by the customer. - `last_payment_amount` number, float: The amount of the customer's last payment. - `is_premium_customer` boolean: Specifies whether the customer is a premium customer. - `is_returning_customer` boolean: Specifies whether the customer is a returning customer. - `lifetime_value` number, float: The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following: - canceled orders - rejected payments - refunded payments - Tamara payments The lifetime value is an indicator of how valuable the relationship with the customer is to your company. - `shipping` object: The address any products are being sent to. - `address` Address, required - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `billing` object, required: The billing details. - `address` Address, required - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `recipient` PaymentInterfacesRecipient: Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions. - `dob` string, date: The recipient's date of birth, in the format `YYYY-MM-DD`. - `account_number` string: An identifier related to the primary recipient's account. For example, an IBAN, an internal account number, a phone number, or the first six and last four digits of the PAN. - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `first_name` string: The recipient's first name. - `last_name` string: The recipient's last name. - `processing` PaymentInterfacesProcessing: Use the processing object to influence or override the data sent during card processing - `aft` boolean: Indicates whether the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) - `discount_amount` number: The discount amount applied to the transaction by the merchant. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `tax_amount` number: The customer's value-added tax registration number. - `invoice_id` string: Invoice ID number. - `brand_name` string: The label that overrides the business name in the PayPal account on the PayPal pages. - `locale` string: The language and region of the customer in ISO 639-2 language code; value consists of language-country. - `partner_customer_risk_data` object: An array of key-and-value pairs with merchant-specific data for the transaction. - `key` string: The key for the pair. - `value` string: The value for the pair. - `custom_payment_method_ids` string[]: Promo codes - An array that can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, etc.) should be shown for this purchase. - `airline_data` object[]: Contains information about the airline ticket and flights booked by the customer. - `ticket` object: Contains information about the airline ticket. - `number` string: The ticket's unique identifier. - `issue_date` string, date: Date the airline ticket was issued. - `issuing_carrier_code` string: Carrier code of the ticket issuer. - `travel_package_indicator` string: C = Car rental reservation, A = Airline flight reservation, B = Both car rental and airline flight reservations included, N = Unknown. - `travel_agency_name` string: The name of the travel agency. - `travel_agency_code` string: The unique identifier from IATA or ARC for the travel agency that issues the ticket. - `passenger` union: Contains information about the passenger(s) on the flight. PayPal requires a single object. - PaymentInterfacesProcessingAirlinePassengerData[]: Array of passengers on the flight. - `first_name` string: The passenger's first name. - `last_name` string: The passenger's last name. - `date_of_birth` string, date: The passenger's date of birth. - `address` object: Contains information about the passenger's address. - `country` string: The two-letter ISO country code of the passenger's country residence. - PaymentInterfacesProcessingAirlinePassengerData: Contains information about a passenger on the flight. - `first_name` string: The passenger's first name. - `last_name` string: The passenger's last name. - `date_of_birth` string, date: The passenger's date of birth. - `address` object: Contains information about the passenger's address. - `country` string: The two-letter ISO country code of the passenger's country residence. - `flight_leg_details` object[]: Contains information about the flight leg(s) booked by the customer. - `flight_number` string: The flight identifier. - `carrier_code` string: The IATA 2-letter accounting code (PAX) that identifies the carrier. This field is required if the airline data includes leg details. - `class_of_travelling` string: A one-letter travel class identifier. The following are common: F = First class, J = Business class, Y = Economy class, W = Premium economy. - `departure_airport` string: The IATA three-letter airport code of the departure airport. This field is required if the airline data includes leg details. - `departure_date` string, date: The date of the scheduled take off. - `departure_time` string: The time of the scheduled take off. - `arrival_airport` string: The IATA 3-letter airport code of the destination airport. This field is required if the airline data includes leg details. - `stop_over_code` string: A one-letter code that indicates whether the passenger is entitled to make a stopover. Can be a space, O if the passenger is entitled to make a stopover, or X if they are not. - `fare_basis_code` string: The fare basis code, alphanumeric. - `accommodation_data` object[]: Contains information about the accommodation booked by the customer. - `name` string: For lodging, contains the lodging name that appears on the storefront/customer receipts. For cruise, contains the ship name booked for the cruise. - `booking_reference` string: A unique identifier for the booking. - `check_in_date` string, date: For lodging, contains the actual or scheduled date the guest checked-in. For cruise, contains the cruise departure date also known as sail date. - `check_out_date` string, date: For lodging, contains the actual or scheduled date the guest checked-out. For cruise, contains the cruise return date also known as sail end date. - `address` object: The address details of the accommodation. - `address_line1` string: The first line of the address. - `zip` string: The postal code for the address. - `state` string: The state or province of the address country (ISO 3166-2 code of up to two alphanumeric characters). - `country` string: The ISO country code of the address. - `city` string: The address city. - `number_of_rooms` integer: The total number of rooms booked for the accommodation. - `guests` object[]: Contains information about the guests staying at the accommodation. - `first_name` string: The first name of the guest. - `last_name` string: The last name of the guest. - `date_of_birth` string, date: The date of birth of the guest. - `room` object[]: Contains information about the rooms booked by the customer. - `rate` string: For lodging, contains the nightly rate for one room. For cruise, contains the total cost of the cruise. - `number_of_nights_at_room_rate` string: For lodging, contains the number of nights charged at the rate provided in the rate field. For cruise, contains the length of the cruise in days. - `order_id` string: The number provided by the cardholder. Purchase order or invoice number may be used. - `surcharge_amount` integer: Surcharge amount applied to the transaction in minor units by the merchant. - `duty_amount` number: The total charges for any import/export duty included in the transaction. - `shipping_tax_amount` number: The tax amount of the freight or shipping and handling charges for the transaction. - `affiliate_id` string: The unique identifier for Visa-registered ramp providers. Must only contain alphanumeric characters. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - `affiliate_url` string: The affiliate URL. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - `purchase_country` string: The purchase country of the customer. ISO 3166 alpha-2 purchase country. - `merchant_initiated_reason` 'Delayed_charge' | 'Resubmission' | 'No_show' | 'Reauthorization': Indicates the reason for a merchant-initiated payment request. - `campaign_id` integer: Unique number of the campaign this payment will be running in. Only required for Afterpay campaign invoices. - `original_order_amount` number: The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order. - `receipt_id` string: Merchant receipt ID. - `merchant_callback_url` string: A URL which you can use to notify the customer that the order has been created. - `line_of_business` string: Beta

The line of business that the payment is associated with. - `pan_preference` 'fpan' | 'dpan': Specifies the preferred type of Primary Account Number (PAN) for the payment: * DPAN: Uses the Checkout.com Network Token. * FPAN: Uses the full card number. **Note**: This only works when `source.type` is any of: - `cards` - `instruments` - `tokens` - `provision_network_token` boolean: Indicates whether to provision a network token for the payment. - `reconciliation_id` string: Transaction identifier used to track a payment request - `aggregator` PaymentInterfacesProcessingAggregator: Contains information about the payment aggregator. - `sub_merchant_id` string: ID that you assigned to the sub-entity. - `aggregator_id_visa` string: Visa identifier of the payment aggregator. - `aggregator_id_mc` string: Mastercard identifier of the payment aggregator. - `allow_payment_methods` PaymentInterfacesPaymentMethodEnum[] - `disabled_payment_methods` PaymentInterfacesPaymentMethodEnum[] - `products` object[]: Contains details about the products in the order. - `reference` string: The item reference or product stock keeping unit (SKU). - `url` string: Link to the line item's product page. - `name` string, required: The descriptive name of the line item. - `quantity` integer, required: The number of line items. - `price` integer, required: The price per item in minor units, including tax but excluding discounts. The exact format depends on the currency. See Calculating the amount. - `metadata` object: Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays. - `3ds` object: Information required for 3D Secure payments. - `enabled` boolean: Whether to process this payment as a 3D Secure payment. - `attempt_n3d` boolean: Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS. - `challenge_indicator` 'no_preference' | 'no_challenge_requested' | 'challenge_requested' | 'challenge_requested_mandate': Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge. - `allow_upgrade` boolean: Whether to process this payment as 3D Secure if the authorization was soft declined because 3DS authentication is required. - `exemption` 'low_value' | 'secure_corporate_payment' | 'trusted_listing' | 'transaction_risk_assessment' | '3ds_outage' | 'sca_delegation' | 'out_of_sca_scope' | 'other' | 'low_risk_program' | 'recurring_operation': Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide. - `risk` object: Configures the risk assessment performed during payment processing. - `enabled` boolean, required: Specifies whether to perform a risk assessment. - `customer_retry` object: Configures the parameters for customer retries. A customer retry is a payment attempt performed by the customer on the checkout page. This differs from [authorization request retries](https://api-reference.checkout.com/#operation/requestAPaymentOrPayout!path=0/retry&t=request) performed in the back end by Checkout.com. - `max_attempts` integer: The maximum number of customer retry attempts, excluding the initial payment attempt. - `sender` PaymentInterfacesSender: The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument. - `return_url` string, uri: If provided, the success page will include a button that redirects your customer to the provided URL. - `locale` 'ar' | 'da-DK' | 'de-DE' | 'el' | 'en-GB' | 'es-ES' | 'fi-FI' | 'fil-PH' | 'fr-FR' | 'hi-IN' | 'id-ID' | 'it-IT' | 'ja-JP' | 'ms-MY' | 'nb-NO' | 'nl-NL' | 'pt-PT' | 'sv-SE' | 'th-TH' | 'vi-VN' | 'zh-CN' | 'zh-HK' | 'zh-TW': Creates a translated version of the page in the specified language - `capture` boolean: Whether to capture the payment (if applicable). - `capture_on` string, date-time: ISO 8601 timestamp - `instruction` object: Details about the payment instruction. - `purpose` 'donations' | 'education' | 'emergency_need' | 'expatriation' | 'family_support' | 'financial_services' | 'gifts' | 'income' | 'insurance' | 'investment' | 'it_services' | 'leisure' | 'loan_payment' | 'medical_treatment' | 'other' | 'pension' | 'royalties' | 'savings' | 'travel_and_tourism': The purpose of the payment. This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response). See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details. - `payment_method_configuration` object: Configuration options for specific payment methods. - `applepay` object: Configuration options specific to Apple Pay payments. - `account_holder` object: The account holder's details. - `type` string, required - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` - `card` object: Configuration options specific to card payments. - `store_payment_details` 'disabled' | 'enabled' | 'collect_consent': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled` or `collect_consent`, you must: - Have obtained consent from the cardholder to store their payment details - Provide `customer.id` or `customer.email` in the request You do not need to provide this field if `payment_type` is set to one of the following values: - `Installment` - `Recurring` - `Unscheduled` - `account_holder` object: The account holder's details. - `googlepay` object: Configuration options specific to Google Pay payments. - `account_holder` object: The account holder's details. - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` ## Response `201` Create Payment Link Page - PaymentLinksResponse - `id` string, required: The unique identifier for a Payment Link. - `expires_on` string, date-time: The date and time when the Payment Link expires. - `reference` string: A reference you can later use to identify this payment, such as an order number. - `warnings` object[]: Related to the `allow_payment_methods` object in the request. Included in the response if an alternative payment method is passed through, but no card schemes are configured against the account. - `code` string: The reason for the warning - `description` string: The description of the warning code - `value` 'card' | 'sofort' | 'ideal' | 'knet' | 'bancontact' | 'eps' | 'p24' | 'multibanco': Payment method for which the warning applies - `_links` object, required: The links related to the Payment Link session. - `self` Link - `href` string, required: The link URL - `redirect` Link - `href` string, required: The link URL ## Other responses - `401`: Unauthorized - `422`: Invalid data was sent --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)