---
title: "Create a client session"
method: POST
path: "/client-session"
tags: ["Client Session API"]
---

# Create a client session

`POST /client-session`

Creating a client session generates a client token: a temporary key used to initialize [Universal Checkout](/docs/get-started/set-up-a-checkout) and authenticate it against your account.

Universal Checkout automatically retrieves all the settings from the client session and the Dashboard to configure the payment methods and the checkout experience.

<b>Note:</b>
When creating a Client Session, please make sure to provide `currencyCode`, `orderId`, and at least one of `amount` or `lineItems`. 
If any of these are not yet available, you can provide them when making the payment request.

<code>POST /client-session</code> does not have required fields as all fields are not always known when a client session is created. 
Use <code>PATCH /client-session</code> to update the parameters throughout the checkout session.

Client tokens expire after 24 hours.

## Headers

- `X-API-VERSION` string, required

## Request body

- ClientSessionAPIRequest
  - `orderId` string — Your reference for the payment.
  - `currencyCode` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SOS' | 'SRD' | 'SSP' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XFU' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' — 3-letter currency code in <a href='https://en.wikipedia.org/wiki/ISO_4217#Active_codes'>ISO 4217</a> format, e.g. <code>USD</code> for US dollars.
  - `amount` integer — The amount you would like to charge the customer, in minor units. e.g. for $7, use `700`. Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use `100`. If the amount is provided on this level, it would override any amount calculated from the provided line items, shipping and other amounts.
  - `order` OrderDetailsAPISchema
    - `lineItems` OrderLineItemsAPISchema[] — The details of the line items of the order.
      - `itemId` string — A unique identifier for the line item.
      - `name` string — A name of the item.
      - `description` string — A description of the item.
      - `amount` integer, required — The amount charged to the customer, in minor units. The minimum amount is 0. The maximum amount is the limit of `int64`.
      - `quantity` integer — The number of the particular line item that is being ordered.
      - `discountAmount` integer — Any discount applicable to this item, in minor units. This discount is applied for the entire line item, and not per `quantity`.
      - `taxAmount` integer — The tax charged on this item, in minor units. This tax amount is applied for the entire line item, and not per `quantity`.
      - `taxCode` string — The tax code associated with this item, in minor units. This is required for Primer-initiated tax calculations.
      - `productType` 'PHYSICAL' | 'DIGITAL' — An enumeration
      - `productData` OrderLineItemsProductDataAPISchema — Details related to the product
        - `sku` string — The product SKU
        - `brand` string — The product brand
        - `color` string — The product color
        - `globalTradeItemNumber` string — The product Global Trade Item Number (e.g. ISBN)
        - `manufacturerPartNumber` string — The product Manufacturer Part Number
        - `weight` number — The product weight
        - `weightUnit` string — The product weight unit (e.g. kg, g)
        - `pageUrl` string — The product page URL
    - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
    - `retailerCountryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
    - `fees` OrderFeesAPISchema[] — The details of fees charged.
      - `amount` integer, required — The fee amount charged to the customer, in minor units. e.g. for $7, use `700`.
      - `type` string — The type of fee.
      - `description` string — A description of the fee, e.g. "Currency Conversion Fee".
    - `shipping` OrderShippingAPISchema
      - `amount` integer — The shipping amount charged to the customer, in minor units. e.g. for $7, use `700`.
      - `methodId` string — Your unique identifier of the shipping method selected by the customer.
      - `methodName` string — The display label for the selected shipping method (e.g. "Standard Shipping").
      - `methodDescription` string — The descriptive text that is displayed alongside the shipping method name.
  - `customerId` string — A unique identifier for your customer. Create a client session token with a `customerId` to enable the client-side SDK to retrieve and manage your customer's saved payment methods. A client session token also enables saving payment methods against this customer id.
  - `customer` CheckoutCustomerDetailsAPISchema
    - `emailAddress` string, email — Customer email address. <br />Must be a valid email address. Supports internationalized email addresses.
    - `mobileNumber` string — The customer's mobile number
    - `firstName` string — The customer's first name
    - `lastName` string — The customer's last name
    - `billingAddress` OptionalAddressAPISchema
      - `firstName` string
      - `lastName` string
      - `addressLine1` string — Street name, Company name or PO Box
      - `addressLine2` string — Apartment, Unit or Building number
      - `city` string — Name of the city, district, town or village
      - `state` string — State, County or Province
      - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
      - `postalCode` string — Postal or ZIP code
    - `shippingAddress` OptionalAddressAPISchema
      - `firstName` string
      - `lastName` string
      - `addressLine1` string — Street name, Company name or PO Box
      - `addressLine2` string — Apartment, Unit or Building number
      - `city` string — Name of the city, district, town or village
      - `state` string — State, County or Province
      - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
      - `postalCode` string — Postal or ZIP code
    - `taxId` string — The customer's tax id number for tax exemptions
    - `nationalDocumentId` string — The customer's national identification number
  - `metadata` object — Additional data to be used throughout the payment lifecycle. A dictionary of key-value pairs where the values can only be strings or integers. e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}` The size of `metadata` must not exceed 300 KB (307,200 bytes) when serialized as JSON. Larger payloads are rejected with a `PaymentMetadataSizeExceeded` error.
  - `paymentMethod` CheckoutRequestPaymentMethodOptionsAPISchema
    - `vaultOnSuccess` boolean — Whether the payment method should be vaulted on a successful payment or not.
    - `vaultOn3DS` boolean — Whether the payment method should be vaulted after a successful 3DS authentication or not.
    - `vaultOnAgreement` boolean — Whether the payment method should be vaulted right when payment is created or not.
    - `descriptor` string — A description of the payment, as it would typically appear on a bank statement.
    - `paymentType` 'FIRST_PAYMENT' | 'ECOMMERCE' | 'SUBSCRIPTION' | 'UNSCHEDULED' — Payment types, primarily to be used for recurring payments. See the table below for all possible values. Note: if no field is set, we will return a blank value and make a best effort to calculate the downstream fields required for processing the payment. | paymentType | Use case | | --- | --- | | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario. | | `ECOMMERCE` | a customer-initiated payment using stored payment details where the cardholder is present. | | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount. | | `UNSCHEDULED` | a merchant-initiated payment using stored payment details with no fixed schedule or amount. |
    - `orderedAllowedCardNetworks` CardNetworkEnum[] — If provided, the checkout will run the validation on the entered card number and raise an error in case the card network is not supported. The order sets the default card network that should be used in the case of co-badged cards. e.g. in the case of `["VISA", "CARTES_BANCAIRES", "MASTERCARD"]` - if the user enters a "Visa" / "Cartes Bancaires" card: the default is Visa. Values should be unique. If `null` or nothing passed in the request, the following list with all card networks will be returned in the response: `["VISA", "MASTERCARD", "AMEX", "MAESTRO", "UNIONPAY", "CARTES_BANCAIRES", "DANKORT", "DINERS_CLUB", "DISCOVER", "EFTPOS", "ENROUTE", "ELO", "HIPER", "INTERAC", "JCB", "MIR", "OTHER"]`
    - `options` object — Additional options for the payment methods represented as dictionary with key of [available payment methods](https://primer.io/docs/connections/payment-methods/available-payment-methods) and value of corresponding options.
      - `<PAYMENT_METHOD_TYPE>` CheckoutPaymentMethodOptionAPISchema — Options for the payment method of type `PAYMENT_METHOD_TYPE`.
        - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema, required
          - `amount` integer — The surcharge amount, in minor units. Surcharge amount must be used in conjunction with line item amounts, if a top level amount is passed then surcharge will not be calculated.
        - `extraMerchantData` CheckoutPaymentMethodOptionExtraMerchantDataAPISchema
        - `merchantName` string — For payments using the Apple Pay payment method, use this field to override the default merchant name for the Primer account from showing on the Apple Pay flow. For example, if your merchant name on your account is "Company X" but you want to display a specific store name on the Apple Pay flow, you can set the `merchantName` to "Store name A".
      - `APPLE_PAY` CheckoutPaymentMethodApplePayOptionAPISchema — Apple Pay configuration used in a client session's payment method options.
        - `merchantName` string — Display name for the merchant shown in the Apple Pay sheet.
        - `recurringPaymentRequest` ApplePayRecurringRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `regularBilling` ApplePayRegularBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `recurringStartDate` string, date-time — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). If not provided, Apple Pay defaults it to now().
            - `recurringEndDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            - `recurringIntervalUnit` 'minute' | 'hour' | 'day' | 'month' | 'year' — Calendar unit representing part of a recurring billing interval.
            - `recurringIntervalCount` integer — Number of calendar units that make up the full recurring interval (e.g., 1 = monthly).
          - `trialBilling` ApplePayTrialBilling
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `recurringStartDate` string, date-time — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). If not provided, Apple Pay defaults it to now().
            - `recurringEndDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            - `recurringIntervalUnit` 'minute' | 'hour' | 'day' | 'month' | 'year' — Calendar unit representing part of a recurring billing interval.
            - `recurringIntervalCount` integer — Number of calendar units that make up the full recurring interval (e.g., 1 = monthly).
        - `deferredPaymentRequest` ApplePayDeferredRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `deferredBilling` ApplePayDeferredBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `deferredPaymentDate` string, date-time, required — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
          - `freeCancellationDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
          - `freeCancellationTimeZone` string — Time zone for interpreting freeCancellationDate.
        - `automaticReloadRequest` ApplePayAutomaticReloadRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `automaticReloadBilling` ApplePayAutomaticReloadBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `automaticReloadThresholdAmount` integer, required — Balance threshold in minor units (e.g., 500 = $5.00) that triggers the reload.
      - `PAYMENT_CARD` CheckoutPaymentMethodCardOptionAPISchema
        - `networks` CheckoutPaymentMethodOptionCardNetworkAPISchema
          - `AMEX` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `CARTES_BANCAIRES` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DANKORT` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DINERS_CLUB` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DISCOVER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `ENROUTE` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `ELO` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `HIPER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `INTERAC` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `JCB` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MAESTRO` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MASTERCARD` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MIR` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `PRIVATE_LABEL` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `UNIONPAY` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `VISA` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `OTHER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
        - `captureVaultedCardCvv` boolean — Whether to capture CVV for vaulted card.
    - `authorizationType` 'ESTIMATED' | 'FINAL' — Type of authorization for the payment.
    - `firstPaymentReason` 'CardOnFile' | 'Recurring' | 'Unscheduled' — The reason for the first payment. This is used for informing payment processors about the specific reason a payment method is being stored. Defaults to None if not provided.

## Response `200`

Successful Response

- ClientSessionWithTokenAPIResponse
  - `clientToken` string, required — Client token used to initialize the SDK on all platforms.
  - `clientTokenExpirationDate` string, date-time, required — Expiration date & time of the client token (UTC with no timezoneinfo).
  - `orderId` string — Your reference for the payment.
  - `currencyCode` string — The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars.
  - `amount` integer — The amount you would like to charge the customer, in minor units. e.g. for $7, use `700`. Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use `100`. If the amount is provided on this level, it would override any amount calculated from the provided line items, shipping and other amounts.
  - `order` OrderDetailsAPISchema
    - `lineItems` OrderLineItemsAPISchema[] — The details of the line items of the order.
      - `itemId` string — A unique identifier for the line item.
      - `name` string — A name of the item.
      - `description` string — A description of the item.
      - `amount` integer, required — The amount charged to the customer, in minor units. The minimum amount is 0. The maximum amount is the limit of `int64`.
      - `quantity` integer — The number of the particular line item that is being ordered.
      - `discountAmount` integer — Any discount applicable to this item, in minor units. This discount is applied for the entire line item, and not per `quantity`.
      - `taxAmount` integer — The tax charged on this item, in minor units. This tax amount is applied for the entire line item, and not per `quantity`.
      - `taxCode` string — The tax code associated with this item, in minor units. This is required for Primer-initiated tax calculations.
      - `productType` 'PHYSICAL' | 'DIGITAL' — An enumeration
      - `productData` OrderLineItemsProductDataAPISchema — Details related to the product
        - `sku` string — The product SKU
        - `brand` string — The product brand
        - `color` string — The product color
        - `globalTradeItemNumber` string — The product Global Trade Item Number (e.g. ISBN)
        - `manufacturerPartNumber` string — The product Manufacturer Part Number
        - `weight` number — The product weight
        - `weightUnit` string — The product weight unit (e.g. kg, g)
        - `pageUrl` string — The product page URL
    - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
    - `retailerCountryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
    - `fees` OrderFeesAPISchema[] — The details of fees charged.
      - `amount` integer, required — The fee amount charged to the customer, in minor units. e.g. for $7, use `700`.
      - `type` string — The type of fee.
      - `description` string — A description of the fee, e.g. "Currency Conversion Fee".
    - `shipping` OrderShippingAPISchema
      - `amount` integer — The shipping amount charged to the customer, in minor units. e.g. for $7, use `700`.
      - `methodId` string — Your unique identifier of the shipping method selected by the customer.
      - `methodName` string — The display label for the selected shipping method (e.g. "Standard Shipping").
      - `methodDescription` string — The descriptive text that is displayed alongside the shipping method name.
  - `customerId` string — A unique identifier for your customer.
  - `customer` CustomerDetailsAPISchema
    - `emailAddress` string, email — Customer email address. Note: It is recommended to include this field if a 3DS check will be performed
    - `mobileNumber` string — The customer's mobile number
    - `firstName` string — The customer's first name
    - `lastName` string — The customer's last name
    - `billingAddress` OptionalAddressAPISchema
      - `firstName` string
      - `lastName` string
      - `addressLine1` string — Street name, Company name or PO Box
      - `addressLine2` string — Apartment, Unit or Building number
      - `city` string — Name of the city, district, town or village
      - `state` string — State, County or Province
      - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
      - `postalCode` string — Postal or ZIP code
    - `shippingAddress` OptionalAddressAPISchema
      - `firstName` string
      - `lastName` string
      - `addressLine1` string — Street name, Company name or PO Box
      - `addressLine2` string — Apartment, Unit or Building number
      - `city` string — Name of the city, district, town or village
      - `state` string — State, County or Province
      - `countryCode` 'AW' | 'AF' | 'AO' | 'AI' | 'AX' | 'AL' | 'AD' | 'AE' | 'AR' | 'AM' | 'AS' | 'AQ' | 'TF' | 'AG' | 'AU' | 'AT' | 'AZ' | 'BI' | 'BE' | 'BJ' | 'BQ' | 'BF' | 'BD' | 'BG' | 'BH' | 'BS' | 'BA' | 'BL' | 'BY' | 'BZ' | 'BM' | 'BO' | 'BR' | 'BB' | 'BN' | 'BT' | 'BV' | 'BW' | 'CF' | 'CA' | 'CC' | 'CH' | 'CL' | 'CN' | 'CI' | 'CM' | 'CD' | 'CG' | 'CK' | 'CO' | 'KM' | 'CV' | 'CR' | 'CU' | 'CW' | 'CX' | 'KY' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DM' | 'DK' | 'DO' | 'DZ' | 'EC' | 'EG' | 'ER' | 'EH' | 'ES' | 'EE' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FR' | 'FO' | 'FM' | 'GA' | 'GB' | 'GE' | 'GG' | 'GH' | 'GI' | 'GN' | 'GP' | 'GM' | 'GW' | 'GQ' | 'GR' | 'GD' | 'GL' | 'GT' | 'GF' | 'GU' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IM' | 'IN' | 'IO' | 'IE' | 'IR' | 'IQ' | 'IS' | 'IL' | 'IT' | 'JM' | 'JE' | 'JO' | 'JP' | 'KZ' | 'KE' | 'KG' | 'KH' | 'KI' | 'KN' | 'KR' | 'KW' | 'LA' | 'LB' | 'LR' | 'LY' | 'LC' | 'LI' | 'LK' | 'LS' | 'LT' | 'LU' | 'LV' | 'MO' | 'MF' | 'MA' | 'MC' | 'MD' | 'MG' | 'MV' | 'MX' | 'MH' | 'MK' | 'ML' | 'MT' | 'MM' | 'ME' | 'MN' | 'MP' | 'MZ' | 'MR' | 'MS' | 'MQ' | 'MU' | 'MW' | 'MY' | 'YT' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NU' | 'NL' | 'NO' | 'NP' | 'NR' | 'NZ' | 'OM' | 'PK' | 'PA' | 'PN' | 'PE' | 'PH' | 'PW' | 'PG' | 'PL' | 'PR' | 'KP' | 'PT' | 'PY' | 'PS' | 'PF' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SA' | 'SD' | 'SN' | 'SG' | 'GS' | 'SH' | 'SJ' | 'SB' | 'SL' | 'SV' | 'SM' | 'SO' | 'PM' | 'RS' | 'SS' | 'ST' | 'SR' | 'SK' | 'SI' | 'SE' | 'SZ' | 'SX' | 'SC' | 'SY' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TM' | 'TL' | 'TO' | 'TT' | 'TN' | 'TR' | 'TV' | 'TW' | 'TZ' | 'UG' | 'UA' | 'UM' | 'UY' | 'US' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW' — 2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.
      - `postalCode` string — Postal or ZIP code
    - `taxId` string — The customer's tax id number for tax exemptions
    - `nationalDocumentId` string — The customer's national identification number
  - `metadata` object — Additional data to be used throughout the payment lifecycle.
  - `paymentMethod` CheckoutResponsePaymentMethodOptionsAPISchema, required
    - `vaultOnSuccess` boolean, required — Whether the payment method should be vaulted on a successful payment or not.
    - `vaultOn3DS` boolean, required — Whether the payment method should be vaulted after a successful 3DS authentication or not.
    - `vaultOnAgreement` boolean, required — Whether the payment method should be vaulted right when payment is created or not.
    - `descriptor` string — A description of the payment, as it would typically appear on a bank statement.
    - `paymentType` 'FIRST_PAYMENT' | 'ECOMMERCE' | 'SUBSCRIPTION' | 'UNSCHEDULED' — Payment types, primarily to be used for recurring payments. See the table below for all possible values. Note: if no field is set, we will return a blank value and make a best effort to calculate the downstream fields required for processing the payment. | paymentType | Use case | | --- | --- | | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario. | | `ECOMMERCE` | a customer-initiated payment using stored payment details where the cardholder is present. | | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount. | | `UNSCHEDULED` | a merchant-initiated payment using stored payment details with no fixed schedule or amount. |
    - `orderedAllowedCardNetworks` CardNetworkEnum[], required — If provided, the checkout will run the validation on the entered card number and raise an error in case the card network is not supported. The order sets the default card network that should be used in the case of co-badged cards. e.g. in the case of `["VISA", "CARTES_BANCAIRES", "MASTERCARD"]` - if the user enters a "Visa" / "Cartes Bancaires" card: the default is Visa. Values should be unique. If `null` or nothing passed in the request, the following list with all card networks will be returned in the response: `["VISA", "MASTERCARD", "AMEX", "MAESTRO", "UNIONPAY", "CARTES_BANCAIRES", "DANKORT", "DINERS_CLUB", "DISCOVER", "EFTPOS", "ENROUTE", "ELO", "HIPER", "INTERAC", "JCB", "MIR", "OTHER"]`
    - `options` object — Additional options for the payment methods represented as dictionary with key of [available payment methods](https://primer.io/docs/connections/payment-methods/available-payment-methods) and value of corresponding options.
      - `<PAYMENT_METHOD_TYPE>` CheckoutPaymentMethodOptionAPISchema — Options for the payment method of type `PAYMENT_METHOD_TYPE`.
        - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema, required
          - `amount` integer — The surcharge amount, in minor units. Surcharge amount must be used in conjunction with line item amounts, if a top level amount is passed then surcharge will not be calculated.
        - `extraMerchantData` CheckoutPaymentMethodOptionExtraMerchantDataAPISchema
        - `merchantName` string — For payments using the Apple Pay payment method, use this field to override the default merchant name for the Primer account from showing on the Apple Pay flow. For example, if your merchant name on your account is "Company X" but you want to display a specific store name on the Apple Pay flow, you can set the `merchantName` to "Store name A".
      - `APPLE_PAY` CheckoutPaymentMethodApplePayOptionAPISchema — Apple Pay configuration used in a client session's payment method options.
        - `merchantName` string — Display name for the merchant shown in the Apple Pay sheet.
        - `recurringPaymentRequest` ApplePayRecurringRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `regularBilling` ApplePayRegularBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `recurringStartDate` string, date-time — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). If not provided, Apple Pay defaults it to now().
            - `recurringEndDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            - `recurringIntervalUnit` 'minute' | 'hour' | 'day' | 'month' | 'year' — Calendar unit representing part of a recurring billing interval.
            - `recurringIntervalCount` integer — Number of calendar units that make up the full recurring interval (e.g., 1 = monthly).
          - `trialBilling` ApplePayTrialBilling
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `recurringStartDate` string, date-time — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). If not provided, Apple Pay defaults it to now().
            - `recurringEndDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            - `recurringIntervalUnit` 'minute' | 'hour' | 'day' | 'month' | 'year' — Calendar unit representing part of a recurring billing interval.
            - `recurringIntervalCount` integer — Number of calendar units that make up the full recurring interval (e.g., 1 = monthly).
        - `deferredPaymentRequest` ApplePayDeferredRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `deferredBilling` ApplePayDeferredBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `deferredPaymentDate` string, date-time, required — Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
          - `freeCancellationDate` string, date-time — End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
          - `freeCancellationTimeZone` string — Time zone for interpreting freeCancellationDate.
        - `automaticReloadRequest` ApplePayAutomaticReloadRequest
          - `paymentDescription` string — Text shown to the user during Apple Pay authorization.
          - `billingAgreement` string — Terms and conditions the user agrees to when authorizing Apple Pay billing.
          - `managementUrl` string, uri, required — URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.
          - `automaticReloadBilling` ApplePayAutomaticReloadBilling, required
            - `label` string, required — Display label shown in the Apple Pay sheet to describe this billing option.
            - `amount` integer — Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., ¥100 = 100).
            - `automaticReloadThresholdAmount` integer, required — Balance threshold in minor units (e.g., 500 = $5.00) that triggers the reload.
      - `PAYMENT_CARD` CheckoutPaymentMethodCardOptionAPISchema
        - `networks` CheckoutPaymentMethodOptionCardNetworkAPISchema
          - `AMEX` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `CARTES_BANCAIRES` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DANKORT` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DINERS_CLUB` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `DISCOVER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `ENROUTE` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `ELO` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `HIPER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `INTERAC` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `JCB` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MAESTRO` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MASTERCARD` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `MIR` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `PRIVATE_LABEL` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `UNIONPAY` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `VISA` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
          - `OTHER` CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
            - `surcharge` CheckoutPaymentMethodOptionSurchargeAPISchema
              - …
        - `captureVaultedCardCvv` boolean — Whether to capture CVV for vaulted card.
    - `authorizationType` 'ESTIMATED' | 'FINAL' — Type of authorization for the payment.
    - `firstPaymentReason` 'CardOnFile' | 'Recurring' | 'Unscheduled' — The reason for the first payment. This is used for informing payment processors about the specific reason a payment method is being stored. Defaults to None if not provided.
  - `warnings` ClientSessionWarningsAPIResponse
    - `type` string, required — The type of the connection involved
    - `code` string, required — A unique code describing the particular issue
    - `message` string, required — More information as to the reason for the warning

## Other responses

- `400` — Error Response
- `422` — Error Response

---

[API](https://skmtc.dev/primer/apis/primer-api.md) · [All operations](https://skmtc.dev/primer/apis/primer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primer/primer-api/revisions/a4459530edb7/schema)