Client Session API

Create a client session

POST

Creating a client session generates a client token: a temporary key used to initialize Universal Checkout 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 w hen 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.

Request

This endpoint expects an object.
orderId
stringOptional
Your reference for the payment.
currencyCode
enumOptional

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

amount
integerOptional

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
objectOptional
More information associated with the order.
customerId
stringOptional

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
objectOptional
More information associated with the customer.
metadata
map from strings to anyOptional

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"}

paymentMethod
objectOptional
Enable certain options associated with the payment method.

Response

This endpoint returns an object
clientToken
string
Client token used to initialize the SDK on all platforms.
clientTokenExpirationDate
datetime
Expiration date & time of the client token (UTC with no timezoneinfo).
orderId
stringOptional
Your reference for the payment.
currencyCode
stringOptional

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

amount
integerOptional

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
objectOptional
More information associated with the order.
customerId
stringOptional
A unique identifier for your customer.
customer
objectOptional
More information associated with the customer.
metadata
map from strings to anyOptional
Additional data to be used throughout the payment lifecycle.
paymentMethod
objectOptional
Enable certain options associated with the payment methods.
warnings
objectOptional
Warning messages to indicate missing information that are required for payment methods, checkout modules and other features; or when third-party services are unavailable.

Errors

POST
$curl -X POST https://api.sandbox.primer.io/client-session \
>     -H "X-API-KEY: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "currencyCode": "AED",
>  "order": {
>    "lineItems": [
>      {
>        "amount": 1,
>        "productType": "PHYSICAL",
>        "productData": {}
>      }
>    ],
>    "countryCode": "AW",
>    "retailerCountryCode": "AW",
>    "fees": [
>      {
>        "amount": 1
>      }
>    ],
>    "shipping": {}
>  },
>  "customer": {
>    "billingAddress": {
>      "countryCode": "AW"
>    },
>    "shippingAddress": {
>      "countryCode": "AW"
>    }
>  },
>  "paymentMethod": {
>    "paymentType": "FIRST_PAYMENT",
>    "orderedAllowedCardNetworks": [
>      "AMEX"
>    ],
>    "options": {
>      "<PAYMENT_METHOD_TYPE>": {
>        "surcharge": {}
>      },
>      "PAYMENT_CARD": {
>        "networks": {
>          "AMEX": {
>            "surcharge": {}
>          },
>          "CARTES_BANCAIRES": {
>            "surcharge": {}
>          },
>          "DANKORT": {
>            "surcharge": {}
>          },
>          "DINERS_CLUB": {
>            "surcharge": {}
>          },
>          "DISCOVER": {
>            "surcharge": {}
>          },
>          "ENROUTE": {
>            "surcharge": {}
>          },
>          "ELO": {
>            "surcharge": {}
>          },
>          "HIPER": {
>            "surcharge": {}
>          },
>          "INTERAC": {
>            "surcharge": {}
>          },
>          "JCB": {
>            "surcharge": {}
>          },
>          "MAESTRO": {
>            "surcharge": {}
>          },
>          "MASTERCARD": {
>            "surcharge": {}
>          },
>          "MIR": {
>            "surcharge": {}
>          },
>          "PRIVATE_LABEL": {
>            "surcharge": {}
>          },
>          "UNIONPAY": {
>            "surcharge": {}
>          },
>          "VISA": {
>            "surcharge": {}
>          },
>          "OTHER": {
>            "surcharge": {}
>          }
>        }
>      }
>    },
>    "authorizationType": "ESTIMATED"
>  }
>}'
Response
1{
2  "clientToken": "string",
3  "clientTokenExpirationDate": "2024-01-15T09:30:00Z",
4  "order": {
5    "lineItems": [
6      {
7        "amount": 1,
8        "productType": "PHYSICAL",
9        "productData": {}
10      }
11    ],
12    "countryCode": "AW",
13    "retailerCountryCode": "AW",
14    "fees": [
15      {
16        "amount": 1
17      }
18    ],
19    "shipping": {}
20  },
21  "customer": {
22    "billingAddress": {
23      "countryCode": "AW"
24    },
25    "shippingAddress": {
26      "countryCode": "AW"
27    }
28  },
29  "paymentMethod": {
30    "paymentType": "FIRST_PAYMENT",
31    "orderedAllowedCardNetworks": [
32      "AMEX"
33    ],
34    "options": {
35      "<PAYMENT_METHOD_TYPE>": {
36        "surcharge": {}
37      },
38      "PAYMENT_CARD": {
39        "networks": {
40          "AMEX": {
41            "surcharge": {}
42          },
43          "CARTES_BANCAIRES": {
44            "surcharge": {}
45          },
46          "DANKORT": {
47            "surcharge": {}
48          },
49          "DINERS_CLUB": {
50            "surcharge": {}
51          },
52          "DISCOVER": {
53            "surcharge": {}
54          },
55          "ENROUTE": {
56            "surcharge": {}
57          },
58          "ELO": {
59            "surcharge": {}
60          },
61          "HIPER": {
62            "surcharge": {}
63          },
64          "INTERAC": {
65            "surcharge": {}
66          },
67          "JCB": {
68            "surcharge": {}
69          },
70          "MAESTRO": {
71            "surcharge": {}
72          },
73          "MASTERCARD": {
74            "surcharge": {}
75          },
76          "MIR": {
77            "surcharge": {}
78          },
79          "PRIVATE_LABEL": {
80            "surcharge": {}
81          },
82          "UNIONPAY": {
83            "surcharge": {}
84          },
85          "VISA": {
86            "surcharge": {}
87          },
88          "OTHER": {
89            "surcharge": {}
90          }
91        }
92      }
93    },
94    "authorizationType": "ESTIMATED"
95  },
96  "warnings": {
97    "type": "TAXJAR",
98    "code": "MISSING_DATA"
99  }
100}
Built with