Client Session API

Retrieve a client session

Changed on Sep 30, 2026

This API call retrieves all the details associated with the client session corresponding to the client token that is provided in the request. The fields with empty values are excluded from the response.

get/client-session

Request

Base URL
https://api.sandbox.primer.io
URL
https://api.sandbox.primer.io/client-session
Auth
API key in header X-API-KEY

Query parameters

clientTokenstring required

Client token

Client token corresponding to the client session to retrieve

Headers

X-API-VERSIONstring required

Example:2.4

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

Response

Successful Response

customerIdstring

A unique identifier for your customer.

orderIdstring

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' | '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'

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.

The following currencies have been retired and will return a deprecation error on new payment or session creation requests: BGN, ZWL, ANG

amountinteger

The amount you are going to charge the customer, in minor units. This amount is calculated from the line items, shipping and other amounts provided in the order. If a top-level amount is provided, it would override any calculated amount.

metadataobject

Additional data to be used throughout the payment lifecycle.

orderedAllowedCardNetworksCardNetworkEnum[]

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

approvalMode'AUTO' | 'MANUAL'

How payment attempts made with a client session are approved.

AUTO: payments are created as soon as the customer submits the checkout.

MANUAL: each payment attempt is held until your backend approves or aborts it via the Payment Attempts API.

currentAttemptIdstring 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.

Example response

{
  "customerId": "customer-123",
  "orderId": "order-abc",
  "currencyCode": "GBP",
  "amount": 650,
  "metadata": {
    "productType": "Clothing"
  },
  "customer": {
    "emailAddress": "john@primer.io"
  },
  "order": {
    "lineItems": [
      {
        "itemId": "t-shirt-1",
        "description": "White T-Shirt",
        "amount": 500,
        "quantity": 1
      }
    ],
    "fees": [
      {
        "type": "SURCHARGE",
        "amount": 100
      }
    ],
    "shipping": {
      "amount": 50
    },
    "paymentMethod": {
      "vaultOnSuccess": false,
      "vaultOn3DS": false,
      "options": {
        "GOOGLE_PAY": {
          "surcharge": {
            "amount": 100
          }
        },
        "PAYMENT_CARD": {
          "networks": {
            "VISA": {
              "surcharge": {
                "amount": 10
              }
            },
            "MASTERCARD": {
              "surcharge": {
                "amount": 20
              }
            }
          }
        },
        "PAY_NL_IDEAL": {
          "surcharge": {
            "amount": 50
          }
        }
      }
    },
    "authorizationType": "ESTIMATED"
  }
}

Changes

Sep 30, 20266b60d7283338 Revision changes
- breaking
  the query request parameter clientToken became required
- warning
  added the new EFTPOS enum value to the // response property for the response status
- warning
  added the new SLE enum value to the response property for the response status
- warning
  added the new STN enum value to the response property for the response status
- warning
  added the new VED enum value to the response property for the response status
- warning
  added the new VES enum value to the response property for the response status
- warning
  added the new XCG enum value to the response property for the response status
- warning
  added the new ZWG enum value to the response property for the response status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  removed the MRO enum value from the response property for the response status
- info
  removed the XAG enum value from the response property for the response status
- info
  removed the XAU enum value from the response property for the response status
- info
  removed the XBA enum value from the response property for the response status
- info
  removed the XBB enum value from the response property for the response status
- info
  removed the XBC enum value from the response property for the response status
- info
  removed the XBD enum value from the response property for the response status
- info
  removed the XDR enum value from the response property for the response status
- info
  removed the XFU enum value from the response property for the response status
- info
  removed the XPD enum value from the response property for the response status
- info
  removed the XPT enum value from the response property for the response status
- info
  removed the XSU enum value from the response property for the response status
- info
  removed the XTS enum value from the response property for the response status
- info
  removed the XUA enum value from the response property for the response status

Operation history