> ## 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.
# Create a client session
> Creating a client session generates a client token: a temporary key used to initialize [Universal Checkout](/accept-payments/setup-universal-checkout/installation/web) 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.
## OpenAPI
````yaml https://api.schemas.primer.io/api-reference/v2.1/openapi.yaml post /client-session
openapi: 3.0.2
info:
x-logo:
url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
title: Primer API
version: '2.1'
description: Primer API v2.1 specification
servers:
- url: https://api.sandbox.primer.io
- url: https://api.primer.io
security:
- ApiKeyAuth: []
tags:
- name: Client Session API
- name: Payments API
- name: Payment Methods API
paths:
/client-session:
post:
tags:
- Client Session API
summary: Create a client session
description: >
Creating a client session generates a client token: a temporary key used
to initialize [Universal
Checkout](/accept-payments/setup-universal-checkout/installation/web)
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.
operationId: create_client_side_token_client_session_post
requestBody:
content:
application/json:
schema:
title: Request
allOf:
- $ref: '#/components/schemas/ClientSessionAPIRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientSessionWithTokenAPIResponse'
'400':
description: Error Response
content:
application/json:
schema:
$ref: '#/components/schemas/400ErrorResponse'
examples:
ClientSessionValidationError:
summary: The client token is invalid.
value:
error:
errorId: ClientSessionValidationError
description: The client token is invalid.
recoverySuggestion: Please provide a valid client token.
diagnosticsId: '1234567898'
MetadataContainsEmptyKey:
summary: Metadata field contains empty string key.
value:
error:
errorId: MetadataContainsEmptyKey
description: Metadata field contains empty string key.
recoverySuggestion: >-
Either remove empty string keys or provide non-empty
string instead.
diagnosticsId: '1234567898'
'422':
description: Error Response
content:
application/json:
schema:
$ref: '#/components/schemas/422ErrorResponse'
examples:
RequestValidationError:
value:
error:
errorId: RequestValidationError
description: >-
We were unable to validate your request, please check
your payload against /docs/api
diagnosticsId: '1234567898'
validationErrors:
- model: ClientSessionAPIRequest
errors:
- path: $.customerId
description: Value must be a valid string
PaymentMetadataSizeExceeded:
summary: payment_metadata exceeds the maximum allowed size.
value:
error:
errorId: PaymentMetadataSizeExceeded
description: >-
payment_metadata size (327680 bytes) exceeds the maximum
allowed size of 307200 bytes.
recoverySuggestion: >-
Reduce the size of payment_metadata to 307200 bytes or
less.
diagnosticsId: '1234567898'
DeprecatedCurrencyError:
summary: DeprecatedCurrencyError
value:
error:
errorId: DeprecatedCurrencyError
description: BGN is no longer a supported currency
recoverySuggestion: Please use a currently supported currency.
diagnosticsId: '1234567898'
components:
schemas:
ClientSessionAPIRequest:
title: ClientSessionAPIRequest
type: object
properties:
orderId:
title: Order identifier
type: string
description: Your reference for the payment.
currencyCode:
title: Currency
type: string
description: >
The 3-letter currency code in [ISO 4217
format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g.
use `USD` for US dollars.
amount:
title: Payment amount
minimum: 0
type: integer
format: int64
description: >-
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.
order:
title: Order Details
allOf:
- $ref: '#/components/schemas/OrderDetailsAPISchema'
description: More information associated with the order.
customerId:
title: The ID of the customer using the checkout
type: string
description: >-
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.
customer:
title: Customer Details
allOf:
- $ref: '#/components/schemas/CheckoutCustomerDetailsAPISchema'
description: More information associated with the customer.
metadata:
title: Payment Metadata
type: object
description: >
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:
title: Payment Method Options
allOf:
- $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
description: Enable certain options associated with the payment method.
additionalProperties: false
example:
orderId: order-abc
currencyCode: GBP
amount: 1000
order:
lineItems:
- itemId: shoe-123
description: Blue Shoe
amount: 100
quantity: 10
countryCode: FR
customerId: customer-123
customer:
emailAddress: john@primer.io
metadata:
productType: Shoes
paymentMethod:
descriptor: 'Purchase: Shoes'
paymentMethodType: PAYMENT_CARD
vaultOnSuccess: true
options:
PAYMENT_CARD:
networks:
VISA:
surcharge:
amount: 10
GOOGLE_PAY:
surcharge:
amount: 20
ClientSessionWithTokenAPIResponse:
title: ClientSessionWithTokenAPIResponse
type: object
required:
- clientToken
- clientTokenExpirationDate
properties:
clientToken:
title: Client token
type: string
description: >-
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:
title: Expiration Date
type: string
description: >-
Expiration date & time of the client token (UTC with no
timezoneinfo).
format: date-time
orderId:
title: Order ID
type: string
description: Your reference for the payment.
currencyCode:
title: Currency
type: string
description: >
The 3-letter currency code in [ISO 4217
format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g.
use `USD` for US dollars.
amount:
title: Payment amount
minimum: 0
type: integer
format: int64
description: >-
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.
order:
title: Order Details
allOf:
- $ref: '#/components/schemas/OrderDetailsAPISchema'
description: More information associated with the order.
customerId:
title: The ID of the customer using the checkout
type: string
description: A unique identifier for your customer.
customer:
title: Customer Details
allOf:
- $ref: '#/components/schemas/CustomerDetailsAPISchema'
description: More information associated with the customer.
metadata:
title: Payment Metadata
type: object
description: |
Additional data to be used throughout the payment lifecycle.
paymentMethod:
title: Payment Method Options
allOf:
- $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
description: Enable certain options associated with the payment methods.
warnings:
type: array
items:
$ref: '#/components/schemas/ClientSessionWarningsAPIResponse'
description: >-
Warning messages to indicate missing information that are required
for payment methods, checkout modules and other features; or when
third-party services are unavailable.
example:
clientToken: client-session-token
clientExpirationDate: '2019-08-24T14:15:22Z'
customerId: customer-123
orderId: order-abc
currencyCode: GBP
metadata:
productType: Shoe
customer:
emailAddress: john@primer.io
amount: 20
order:
countryCode: FR
fees:
- type: SURCHARGE
amount: 20
paymentMethod:
vaultOnSuccess: true
options:
PAYMENT_CARD:
networks:
VISA:
surcharge:
amount: 10
GOOGLE_PAY:
surcharge:
amount: 20
warnings:
- type: TAXJAR
code: MISSING_DATA
message: Shipping details are required for calculating tax.
400ErrorResponse:
title: 400ErrorResponse
allOf:
- $ref: '#/components/schemas/ErrorObject'
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
422ErrorResponse:
title: 422ErrorResponse
allOf:
- $ref: '#/components/schemas/ErrorObject'
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
OrderDetailsAPISchema:
title: OrderDetailsAPISchema
type: object
properties:
lineItems:
title: Line Items
type: array
items:
$ref: '#/components/schemas/OrderLineItemsAPISchema'
description: The details of the line items of the order.
countryCode:
title: Country Code
allOf:
- $ref: '#/components/schemas/CountryCodeEnum'
description: The country in which the order is created
fees:
title: Fee Details
type: array
items:
$ref: '#/components/schemas/OrderFeesAPISchema'
description: The details of fees charged.
shipping:
title: Shipping Details
allOf:
- $ref: '#/components/schemas/OrderShippingAPISchema'
description: The details of shipping charged.
CheckoutCustomerDetailsAPISchema:
title: CustomerDetailsAPISchema
type: object
properties:
emailAddress:
title: Email Address
type: string
description: |
Customer email address.
format: email
mobileNumber:
title: Mobile Number
type: string
description: The customer's mobile number
maxLength: 255
firstName:
title: First Name
type: string
description: The customer's first name
maxLength: 255
lastName:
title: Last Name
type: string
description: The customer's last name
maxLength: 255
billingAddress:
title: Billing Address
allOf:
- $ref: >-
#/components/schemas/core_api__api__commons__schemas__addess__AddressAPISchema
description: |
Customer billing address.
shippingAddress:
title: Shipping Address
allOf:
- $ref: >-
#/components/schemas/core_api__api__commons__schemas__addess__AddressAPISchema
description: Customer shipping address
taxId:
title: Tax ID
type: string
description: The customer's tax id number for tax exemptions
nationalDocumentId:
title: National Document ID
type: string
description: The customer's national identification number
CheckoutPaymentMethodOptionsAPISchema:
title: PaymentMethodOptionsAPISchema
type: object
properties:
vaultOnSuccess:
type: boolean
description: >-
Whether the payment method should be vaulted on a successful payment
or not.
descriptor:
title: Payment descriptor
type: string
description: >-
A description of the payment, as it would typically appear on a bank
statement.
paymentType:
allOf:
- $ref: '#/components/schemas/RecurringPaymentTypeSchema'
options:
title: Payment Method Options
type: object
description: >
Additional options for the payment methods represented as
dictionary
with key of [available payment
methods](/connections/payment-methods/available-payment-methods) and
value of corresponding options.
properties:
:
type: object
allOf:
- $ref: '#/components/schemas/CheckoutPaymentMethodOptionAPISchema'
PAYMENT_CARD:
type: object
allOf:
- $ref: >-
#/components/schemas/CheckoutPaymentMethodCardOptionAPISchema
CustomerDetailsAPISchema:
title: CustomerDetailsAPISchema
type: object
properties:
emailAddress:
title: Email Address
type: string
description: >
Customer email address.
Note: It is recommended to include this field if a 3DS check will be
performed
format: email
mobileNumber:
title: Mobile Number
type: string
description: The customer's mobile number
maxLength: 255
firstName:
title: First Name
type: string
description: The customer's first name
maxLength: 255
lastName:
title: Last Name
type: string
description: The customer's last name
maxLength: 255
billingAddress:
title: Billing Address
allOf:
- $ref: >-
#/components/schemas/core_api__api__commons__schemas__addess__AddressAPISchema
description: >
Customer billing address.
Note: It is recommended to include this field if a 3DS check will be
performed
shippingAddress:
title: Shipping Address
allOf:
- $ref: >-
#/components/schemas/core_api__api__commons__schemas__addess__AddressAPISchema
description: Customer shipping address
taxId:
title: Tax ID
type: string
description: The customer's tax id number for tax exemptions
nationalDocumentId:
title: National Document ID
type: string
description: The customer's national identification number
ClientSessionWarningsAPIResponse:
title: ClientSessionWarningsAPIResponse
type: object
properties:
type:
type: string
description: The type of the connection involved
example: TAXJAR
code:
type: string
description: A unique code describing the particular issue
example: MISSING_DATA
message:
type: string
description: More information as to the reason for the warning
ErrorObject:
title: ErrorObject
type: object
properties:
errorId:
title: Error ID
type: string
description: An error ID
description:
title: Error description
type: string
description: A human description of the error
recoverySuggestion:
title: Recovery Suggestion
type: string
description: A suggestion on how to recover from the error state
diagnosticsId:
title: Error diagnostics ID
type: string
description: >-
An ID that you can quote when contacting the Primer support team via
our [Support
Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
validationErrors:
title: Validation Errors
type: array
items:
type: object
description: Returned in case of a badly formed request
OrderLineItemsAPISchema:
title: OrderLineItemsAPISchema
description: |
The details of the line items of the order.
The total amount of a line item is calculated like so:
````
totalAmount = (amount * quantity) - discountAmount + taxAmount
```
type: object
required:
- amount
properties:
itemId:
title: Item ID
type: string
description: A unique identifier for the line item.
description:
title: Item ID
type: string
description: A description of the item.
amount:
minimum: 0
type: integer
format: int64
description: >-
The amount charged to the customer, in minor units. The minimum
amount is 0. The maximum amount is the limit of `int64`.
quantity:
type: integer
description: The number of the particular line item that is being ordered.
discountAmount:
title: Discount Amount
minimum: 0
type: integer
format: int64
description: >-
Any discount applicable to this item, in minor units. This discount
is applied for the entire line item, and not per `quantity`.
taxAmount:
title: Tax Amount
type: integer
format: int64
description: >-
The tax charged on this item, in minor units. This tax amount is
applied for the entire line item, and not per `quantity`.
taxCode:
title: Tax Code
type: string
description: >-
The tax code associated with this item, in minor units. This is
required for Primer-initiated tax calculations.
productType:
title: Product Type
allOf:
- $ref: '#/components/schemas/ProductTypeEnum'
description: An identifier for the product type.
CountryCodeEnum:
title: CountryCodeEnum
enum:
- AW
- AF
- AO
- AI
- AX
- AL
- AD
- AE
- AR
- AM
- AS
- AQ
- TF
- AG
- AU
- AT
- AZ
- BI
- BE
- BJ
- BQ
- BF
- BD
- BG
- BH
- BS
- BA
- BL
- BY
- BZ
- BM
- BO
- BR
- BB
- BN
- BT
- BV
- BW
- CF
- CA
- CC
- CH
- CL
- CN
- CI
- CM
- CD
- CG
- CK
- CO
- KM
- CV
- CR
- CU
- CW
- CX
- KY
- CY
- CZ
- DE
- DJ
- DM
- DK
- DO
- DZ
- EC
- EG
- ER
- EH
- ES
- EE
- ET
- FI
- FJ
- FK
- FR
- FO
- FM
- GA
- GB
- GE
- GG
- GH
- GI
- GN
- GP
- GM
- GW
- GQ
- GR
- GD
- GL
- GT
- GF
- GU
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IM
- IN
- IO
- IE
- IR
- IQ
- IS
- IL
- IT
- JM
- JE
- JO
- JP
- KZ
- KE
- KG
- KH
- KI
- KN
- KR
- KW
- LA
- LB
- LR
- LY
- LC
- LI
- LK
- LS
- LT
- LU
- LV
- MO
- MF
- MA
- MC
- MD
- MG
- MV
- MX
- MH
- MK
- ML
- MT
- MM
- ME
- MN
- MP
- MZ
- MR
- MS
- MQ
- MU
- MW
- MY
- YT
- NA
- NC
- NE
- NF
- NG
- NI
- NU
- NL
- 'NO'
- NP
- NR
- NZ
- OM
- PK
- PA
- PN
- PE
- PH
- PW
- PG
- PL
- PR
- KP
- PT
- PY
- PS
- PF
- QA
- RE
- RO
- RU
- RW
- SA
- SD
- SN
- SG
- GS
- SH
- SJ
- SB
- SL
- SV
- SM
- SO
- PM
- RS
- SS
- ST
- SR
- SK
- SI
- SE
- SZ
- SX
- SC
- SY
- TC
- TD
- TG
- TH
- TJ
- TK
- TM
- TL
- TO
- TT
- TN
- TR
- TV
- TW
- TZ
- UG
- UA
- UM
- UY
- US
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- ZA
- ZM
- ZW
description: An enumeration.
OrderFeesAPISchema:
title: OrderFeesAPISchema
type: object
required:
- amount
properties:
amount:
minimum: 0
type: integer
description: >-
The fee amount charged to the customer, in minor units. e.g. for
$7, use `700`.
type:
type: string
description: The type of fee.
description:
type: string
description: A description of the fee, e.g. "Currency Conversion Fee".
OrderShippingAPISchema:
title: OrderShippingAPISchema
type: object
properties:
amount:
minimum: 0
type: integer
format: int64
description: >-
The shipping amount charged to the customer, in minor units. e.g.
for $7, use `700`.
methodId:
title: Shipping method ID
type: string
description: Your identifier for the shipping method.
methodName:
title: Shipping method name
type: string
description: The name of the shipping method, e.g. `Express`.
methodDescription:
title: Shipping method description
type: string
description: A description of the shipping method.
core_api__api__commons__schemas__addess__AddressAPISchema:
title: AddressAPISchema
type: object
properties:
firstName:
title: Firstname
type: string
maxLength: 512
lastName:
title: Lastname
type: string
maxLength: 512
addressLine1:
title: Addressline1
type: string
maxLength: 255
addressLine2:
title: Addressline2
type: string
maxLength: 255
city:
title: City
type: string
maxLength: 255
state:
title: State
type: string
maxLength: 255
countryCode:
$ref: '#/components/schemas/CountryCodeEnum'
postalCode:
title: Postalcode
type: string
maxLength: 255
RecurringPaymentTypeSchema:
type: string
title: Recurring Payment Type
enum:
- FIRST_PAYMENT
- ECOMMERCE
- SUBSCRIPTION
- UNSCHEDULED
description: >-
Payment types, primarily to be used for recurring payments.
Note: If you successfully vault a `SINGLE_USE` token on payment
creation, then there's no need to set a value for this field and it will
be flagged as `FIRST_PAYMENT`. Otherwise, see the table below for all
possible values.
| paymentType | Use case |
| --- | --- |
| `FIRST_PAYMENT` | a customer-initiated payment which is the first in a
series of recurring payments or subscription, or a card on file
scenario.
| `ECOMMERCE` | a customer-initiated payment using stored payment
details where the cardholder is present.
| `SUBSCRIPTION` | a merchant-initiated payment as part of a series of
payments on a fixed schedule and a set amount.
| `UNSCHEDULED` | a merchant-initiated payment using stored payment
details with no fixed schedule or amount.
CheckoutPaymentMethodOptionAPISchema:
title: PaymentMethodOptionAPISchema
type: object
description: |
Options for the payment method of type `PAYMENT_METHOD_TYPE`.
required:
- surcharge
properties:
surcharge:
title: Surcharge
description: Surcharge information
allOf:
- $ref: >-
#/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema
CheckoutPaymentMethodCardOptionAPISchema:
title: Payment Method Card Option
type: object
properties:
networks:
title: Card networks
allOf:
- $ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkAPISchema
description: >-
Dictionary of available card networks as a key with value of Payment
Method Card Network Option.
captureVaultedCardCvv:
type: boolean
description: Whether to capture CVV for vaulted card.
ProductTypeEnum:
title: ProductTypeEnum
enum:
- PHYSICAL
- DIGITAL
type: string
description: An enumeration
CheckoutPaymentMethodOptionSurchargeAPISchema:
title: CheckoutPaymentMethodOptionSurchargeAPISchema
type: object
properties:
amount:
type: integer
format: int64
description: >-
The surcharge amount, in minor units. Surcharge amount must be used
in conjunction with line item amounts, if a top level amount is
passed then surcharge will not be calculated.
CheckoutPaymentMethodOptionCardNetworkAPISchema:
title: Payment Method Card Network Option
type: object
properties:
AMEX:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
DANKORT:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
DINERS_CLUB:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
DISCOVER:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
ENROUTE:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
ELO:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
HIPER:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
INTERAC:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
JCB:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
MAESTRO:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
MASTERCARD:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
MIR:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
PRIVATE_LABEL:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
UNIONPAY:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
VISA:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
OTHER:
$ref: >-
#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
additionalProperties: false
CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema:
type: object
properties:
surcharge:
title: Surcharge
description: Surcharge information
allOf:
- $ref: >-
#/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.