This guide explains how to create and update Client Sessions: the first steps towards accepting Payments with Universal Checkout.

If you wish to manually create merchant-initiated Payments, check our Manage Payments guide instead.


A client session is the starting point for integrating payments at Primer. You can attach all the metadata associated with the order to the client session, and generate a clientToken, a temporary key used to initialize Universal Checkout.

The information you include in the client session is used to conditionally route payments with Workflows, and activate payment methods and other features in Universal Checkout, so pass as much information as you can.

The X-Api-Version specifies the API version information. Earlier, this was supposed to be a date. For example, 2021-10-19. This has changed post API version v2 which was represented by 2021-09-27 date. Starting API version v2.1, the X-Api-Version needs to provide the API version as 2.1. Depending upon the API version specified in the client-session request, your client-session will be processed accordingly with requisite features and options that are available for that version.

See API Reference Changelog to see the differences between API versions.

Here is how the client session request to the Primer API should look like:

curl --location --request \ POST 'https://api.sandbox.primer.io/client-session' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2.2' \ --header 'Content-Type: application/json' --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 4999,    "order": {      "lineItems": [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB",    } }' # Here is a (heavily truncated) example response {  "clientToken": "THE_CHECKOUT_SESSION_TOKEN",  "clientExpirationDate": "2022-03-08T14:00:00Z",  "orderId": "order-abc",  "currencyCode": "GBP",  "amount": 5000,}

The clientToken is a key concept within Primer. You may receive a client token from various places but as long as you pass it to the SDK, Universal Checkout knows where to start/resume the flow.

Create a Client Session

The clientToken is a temporary key used to initialize Universal Checkout, and render the payment methods and checkout options you've configured with the Dashboard.

Generate the first client token by creating a Client Session with POST/client-session.

As a rule of thumb, make sure to pass the following data:

Your reference for the payment.
The 3 letter currency code in ISO 4217 format.
e.g. use USD for US dollars.
  1. order
The details of the line items of the order.

Use the

field to attach arbitrary data. Use this to build custom conditions in Workflows for routing and A/B testing.


Make sure to pass all the information required by the payment methods and features activated on your Dashboard.

client token

Client session request POST/client-session

curl --location --request \ POST 'https://api.sandbox.primer.io/client-session' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2.2' \ --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 4999,    "order": {      "lineItems":  [{        "itemId": "shoes-123",        "description": "Some shoes"        "amount": 2500,        "quantity": 2      }]    } }'


Data you pass when creating a client session is used when creating a payment, unless explicitly overwritten.

Client token response

Check the

array for missing data which may be required to display certain payment methods and checkout modules in the Universal Checkout.

{  "clientToken": "<THE_CLIENT_TOKEN>",  "clientTokenExpirationDate": "2021-08-12T16:14:08.578695",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 5000,  "customerId": "<YOUR_CUSTOMER_ID>",  "metadata": { },  "warnings": [    "Apple Pay is missing 'customerDetails.countryCode'"  ]}

Update a Client Session


Universal Checkout automatically updates the Client Session as it captures more data such as the shipping address.

This section explains how to manually update the Client Session, for instance to update the line items.

Make a request to PATCH/client-session to update the Client Session tied to a Client Token.

curl --location --request \ POST 'https://api.sandbox.primer.io/client-session' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2.2' \ --data '{    "clientToken": "<CLIENT_TOKEN>",    "lineItems": [{      "itemId": "shoes-123",      "description": "Some shoes"      "amount": 2500,      "quantity": 1    }] }'