> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Session

export const ApiEndpoint = ({method, path}) => {
  const getMethodColor = method => {
    switch (method?.toUpperCase()) {
      case "GET":
        return "#0285c7";
      case "POST":
        return "#008d71";
      case "PUT":
        return "#16a34a";
      case "PATCH":
        return "#808080";
      case "DELETE":
        return "#dc2626";
      default:
        return "#6b7280";
    }
  };
  const getEndpointUrl = (method, path) => {
    const endpoints = {
      "POST /client-session": "/api-reference/v2.4/api-reference/client-session-api/create-a-client-session",
      "PATCH /client-session": "/api-reference/v2.4/api-reference/client-session-api/update-client-session",
      "POST /payments": "/api-reference/v2.4/api-reference/payments-api/create-a-payment",
      "POST /payments/<YOUR-PAYMENT-ID>/resume": "/api-reference/v2.4/api-reference/payments-api/resume-payment",
      "POST /payments/<YOUR-PAYMENT-ID>/adjust-authorization": "/api-reference/v2.4/api-reference/payments-api/adjust-authorized-amount",
      "POST /payments/<PAYMENT_ID>/cancel": "/api-reference/v2.4/api-reference/payments-api/cancel-payment",
      "POST /payments/<PAYMENT_ID>/refund": "/api-reference/v2.4/api-reference/payments-api/refund-payment",
      "GET /payments/<PAYMENT_ID>": "/api-reference/v2.4/api-reference/payments-api/get-a-payment",
      "GET /payment-instruments": "/api-reference/v2.4/api-reference/payment-methods-api/list-saved-payment-methods",
      "DELETE /payment-instruments/<PAYMENT_METHOD_TOKEN>": "/api-reference/v2.4/api-reference/payment-methods-api/delete-payment-method-payment-methods-token-delete"
    };
    const key = `${method?.toUpperCase()} ${path}`;
    return endpoints[key] || "#";
  };
  const getPrettyPath = (method, path) => {
    const pathMapping = {
      "POST /payments/<YOUR-PAYMENT-ID>/resume": "/payments/{paymentId}/resume",
      "POST /payments/<YOUR-PAYMENT-ID>/adjust-authorization": "/payments/{paymentId}/adjust-authorization",
      "POST /payments/<PAYMENT_ID>/cancel": "/payments/{paymentId}/cancel",
      "POST /payments/<PAYMENT_ID>/refund": "/payments/{paymentId}/refund",
      "GET /payments/<PAYMENT_ID>": "/payments/{paymentId}",
      "DELETE /payment-instruments/<PAYMENT_METHOD_TOKEN>": "/payment-instruments/{paymentMethodToken}"
    };
    const key = `${method?.toUpperCase()} ${path}`;
    return pathMapping[key] || path;
  };
  const methodColor = getMethodColor(method);
  const url = getEndpointUrl(method, path);
  const displayPath = getPrettyPath(method, path);
  return <div style={{
    display: "inline-flex",
    alignItems: "center",
    cursor: "pointer",
    margin: "2px 0",
    padding: "4px",
    paddingRight: "6px",
    background: "rgb(245, 245, 245)",
    borderRadius: "6px",
    whiteSpace: "nowrap",
    textDecoration: "none"
  }}>
      <a href={url} target="_blank" rel="noopener noreferrer" style={{
    textDecoration: "none",
    border: "none"
  }}>
        <span style={{
    display: "inline-block",
    whiteSpace: "nowrap",
    padding: "0 8px",
    fontSize: "13px",
    lineHeight: "23px",
    borderRadius: "6px",
    fontWeight: 400,
    backgroundColor: methodColor,
    color: "white",
    border: "none"
  }}>
          {method.toUpperCase()}
        </span>
        <code style={{
    padding: "0",
    marginLeft: "4px",
    fontFamily: "monospace",
    color: methodColor,
    border: "none",
    textDecorationColor: methodColor
  }}>
          {displayPath}
        </code>
      </a>
    </div>;
};

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

The information you include in the client session is used in the Dashboard:

* to conditionally route payments with Workflows
* to activate payment methods and other features in Primer Checkout.

So pass as much information as you can!

<Note>
  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, Primer Checkout knows where to start/resume the flow.
</Note>

## Create a client session

On your server, create a client session with <ApiEndpoint method="POST" path="/client-session" />
.

Make sure to pass at least the following data:

| Field             | Description                                                                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId`         | Your reference for the payment. <br /><br /> *Make sure to keep track of orderId - you will later receive updates to the payment via Webhooks. The payment will contain the orderId specified in the client session.* |
| `currencyCode`    | The three-letter currency code in ISO 4217 format. <br /> e.g. use USD for US dollars.                                                                                                                                |
| `order.lineItems` | The details of the line items of the order.                                                                                                                                                                           |

Use the [metadata](/api-reference/v2.4/api-reference/client-session-api/create-a-client-session#body-metadata) field to attach arbitrary data. Use this to build custom conditions in Workflows for routing and A/B testing.

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

<Note>
  Make sure to pass all the information required by the payment methods and features activated on your [Dashboard](https://dashboard.primer.io/).
</Note>

Example request:

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

The body of a successful response contains a [clientToken](/api-reference/v2.4/api-reference/client-session-api/create-a-client-session#response-client-token) that you will use to initialize Primer Checkout.

Check the [warnings](/api-reference/v2.4/api-reference/client-session-api/create-a-client-session#response-warnings) array for missing data which may be required to display certain payment methods and checkout modules in the Primer Checkout.

```json JSON theme={"dark"}
{
	"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'"]
}
```

<Note>
  ️ As a `clientToken` is a temporary key, it has an expiration time of 24 hours.
</Note>

## Update a client session

Primer Checkout automatically updates the Client Session as it captures more data such as the billing address.

Alternatively, you can manually update the Client Session to update the line items or the customer details.

Make a request to <ApiEndpoint method="PATCH" path="/client-session" />
to update the Client Session tied to a Client Token.

```bash BASH theme={"dark"}
curl --location --request \
 PATCH 'https://api.sandbox.primer.io/client-session' \
 --header 'X-Api-Key: <YOUR_API_KEY>' \
 --header 'X-Api-Version: 2.4' \
 --data '{
    "clientToken": "<CLIENT_TOKEN>",
    "order": {
      "lineItems": [{
        "itemId": "shoes-123",
        "description": "Some shoes",
        "amount": 2500,
        "quantity": 1
      }]
    }
 }'
```

Then, call `refreshClientSession()` to ask the Checkout to get the latest client session.

With Drop-in Checkout:

```typescript Typescript theme={"dark"}
const checkout = await Primer.showUniversalCheckout(clientToken, options)

// Refresh the internal client session
await checkout.refreshClientSession()
```

With Headless Checkout:

```typescript Typescript theme={"dark"}
const headless = await Primer.createHeadless(clientToken, options)

// Refresh the internal client session
await headless.refreshClientSession()
```