Client Session API

Update client session

Changed on Sep 30, 2026

You can update a clients session created earlier with the PATCH /client-session API call.

The only required field for the request is clientToken. Other supported request fields are same as for the POST /client-session API call.

You need to specify only the fields you wish to update. However, if the items to be updated are arrays (e.g.lineItems), you need to provide the entire array, including any new or modified items. Primer will replace the full array with whatever is sent in the request. If you want to keep existing items, make sure to include them in your request, anything omitted will be removed.

If you wish to update nested fields on the client session, such as the customer emailAddress field, you can pass the customer object with only one field, emailAddress, to update.

If you simply wish to clear the value of the field, pass null as your input.

You can update paymentMethod.vaultOnSuccess field but updating of the paymentMethod.options field through PATCH /client-session is not supported.

approvalMode and currentAttemptId are immutable: a request that includes either field is rejected with a 422.

The response will contain all the fields of the client session including the ones that were changed.

patch/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

Headers

X-API-VERSIONstring required

Example:2.4

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

Request body

clientTokenstring required

Client token for use in the Primer-JS SDK obtained via POST /client-session API call. Its length is not fixed. Treat it as an opaque string and do not rely on a maximum length when storing it.

customerIdstring

A unique identifier for your customer.

orderIdstring

Your reference for the order.

currencyCodestring

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

amountinteger

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.

metadataobject

Additional data to be used throughout the payment lifecycle.

Provide the entire object to update it. Anything provided previously will be overwritten.

The size of metadata must not exceed 300 KB (307,200 bytes) when serialized as JSON. Larger payloads are rejected with a PaymentMetadataSizeExceeded error.

Example request

{
  "clientToken": "client-session-token",
  "customerId": "customer-123",
  "orderId": "order-abc",
  "customer": {
    "emailAddress": "john@primer.io"
  },
  "amount": 500,
  "paymentMethod": {
    "authorizationType": "FINAL"
  },
  "order": {
    "lineItems": [
      {
        "itemId": "shoe-123",
        "description": "Blue Shoe",
        "amount": 100,
        "quantity": 10
      }
    ],
    "countryCode": "FR"
  }
}

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 request property became required
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- warning
  the request property's maxLength was set to 255
- warning
  the request property's maxLength was set to 255
- 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 new EFTPOS enum value to the request property //
- 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