Create a client session

Creating a client session generates a client token: a temporary key used to initialize Universal 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.

Note: 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.

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

Client tokens expire after 24 hours.

POST /client-session

Create a client session

cURL

curl --request POST \
  --url https://api.sandbox.primer.io/client-session \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '
{
  "orderId": "order-abc",
  "currencyCode": "GBP",
  "amount": 1000,
  "order": {
    "countryCode": "FR,",
    "lineItems": [
      {
        "itemId": "shoe-123",
        "description": "Blue Shoe",
        "amount": 100,
        "quantity": 10
      }
    ]
  },
  "customerId": "customer-123",
  "customer": {
    "emailAddress": "[e-mail]"
  },
  "metadata": {
    "productType": "Shoes"
  },
  "paymentMethod": {
    "descriptor": "Purchase: Shoes",
    "paymentMethodType": "PAYMENT_CARD",
    "vaultOnSuccess": true,
    "vaultOn3DS": false,
    "options": {
      "PAYMENT_CARD": {
        "networks": {
          "VISA": {
            "surcharge": {
              "amount": 10
            }
          }
        }
      },
      "GOOGLE_PAY": {
        "surcharge": {
          "amount": 20
        }
      }
    },
    "authorizationType": "ESTIMATED"
  }
}
'

200

Example

{ "clientToken": "client-session-token", "clientExpirationDate": "2019-08-24T14:15:22Z", "customerId": "customer-123", "orderId": "order-abc", "currencyCode": "GBP", "metadata": { "productType": "Shoe" }, "customer": { "emailAddress": "[e-mail]" }, "amount": 20, "order": { "countryCode": "FR", "fees": [ { "type": "SURCHARGE", "amount": 20 } ] }, "paymentMethod": { "vaultOnSuccess": true, "vaultOn3DS": false, "options": { "PAYMENT_CARD": { "networks": { "VISA": { "surcharge": { "amount": 10 } } }, "captureVaultedCardCvv": true }, "GOOGLE_PAY": { "surcharge": { "amount": 20 } } }, "authorizationType": "ESTIMATED" }, "warnings": [ { "type": "TAXJAR", "code": "MISSING_DATA", "message": "Shipping details are required for calculating tax." } ] }

Authorizations

X-API-KEY · string · header · required

Headers

X-API-VERSION · string · required

Specifies the version of the API to use. This must be set to 2.4.

Example:

"2.4"

Body

application/json

orderId · string

Your reference for the payment.

Required string length: 1 - 255

currencyCode · enum<string>

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

Available options: 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, 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, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW, ZWG, ZWL

amount · integer<int64>

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.

Required range: x >= 0

order · Order Details · object

More information associated with the order.

Show child attributes

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.

Required string length: 1 - 255

customer · Customer Details · object

More information associated with the customer.

Show child attributes

metadata · Payment 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 · Payment Method Options · object

Enable certain options associated with the payment method.

Show child attributes

approvalMode · enum<string> · default: AUTO

Controls whether payments made with this client session are created automatically or require explicit approval from your backend.

AUTO (default): each payment attempt is authorized as soon as the customer submits the checkout.

MANUAL: each payment attempt is held until your backend approves it with POST /payment-attempts/{id}/approve or aborts it with POST /payment-attempts/{id}/abort. See the Manual payment approval guide.

Set at creation only: it cannot be changed with PATCH /client-session.

Available options: AUTO, MANUAL

Response

200

application/json

Successful Response

clientToken · string · required

Client token used to initialize the SDK on all platforms. Its length is not fixed. Treat it as an opaque string and do not rely on a maximum length when storing it.

clientTokenExpirationDate · string<date-time> · required

Expiration date & time of the client token (UTC with no timezoneinfo).

paymentMethod · Payment Method Options · object · required

Enable certain options associated with the payment methods.

Show child attributes

orderId · string

Your reference for the payment.

currencyCode · string

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

amount · integer<int64>

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.

Required range: x >= 0

order · Order Details · object

More information associated with the order.

Show child attributes

customerId · string

A unique identifier for your customer.

customer · Customer Details · object

More information associated with the customer.

Show child attributes

metadata · Payment Metadata · object

Additional data to be used throughout the payment lifecycle.

orderedAllowedCardNetworks · enum<string>[]

The ordered list of card networks accepted for this client session, as resolved from paymentMethod.orderedAllowedCardNetworks and the default list.

The list of available card networks.

Available options: AMEX, DANKORT, DINERS_CLUB, DISCOVER, EFTPOS, ENROUTE, ELO, HIPER, INTERAC, JCB, MAESTRO, MASTERCARD, MIR, PRIVATE_LABEL, UNIONPAY, VISA, CARTES_BANCAIRES, OTHER

warnings · ClientSessionWarningsAPIResponse · object[]

Warning messages to indicate missing information that are required for payment methods, checkout modules and other features; or when third-party services are unavailable.

Show child attributes

approvalMode · enum<string>

The approval mode the client session was created with.

Available options: AUTO, MANUAL

currentAttemptId · string<uuid>

ID of the current payment attempt. Only populated for MANUAL approval mode sessions once the checkout has tokenised a payment method; use it with the Payment Attempts API to approve or abort the attempt.