Skip to main content
POST
/
client-session
Create a client session
curl --request POST \
  --url https://api.sandbox.primer.io/client-session \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "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
        }
      }
    }
  }
}
'
{
  "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."
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Body

application/json
​
orderId
string

Your reference for the payment.

​
currencyCode
string

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

​
amount
integer<int64>

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.

Required range: x >= 0
​
order
Order Details · object

More information associated with the order.

​
customerId
string

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
Customer Details · object

More information associated with the customer.

​
metadata
Payment Metadata · object

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
Payment Method Options · object

Enable certain options associated with the payment method.

Response

Successful Response

​
clientToken
string
required

Client token used to initialize the SDK on all platforms.

​
clientTokenExpirationDate
string<date-time>
required

Expiration date & time of the client token (UTC with no timezoneinfo).

​
orderId
string

Your reference for the payment.

​
currencyCode
string

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

​
amount
integer<int64>

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.

Required range: x >= 0
​
order
Order Details · object

More information associated with the order.

​
customerId
string

A unique identifier for your customer.

​
customer
Customer Details · object

More information associated with the customer.

​
metadata
Payment Metadata · object

Additional data to be used throughout the payment lifecycle.

​
paymentMethod
Payment Method Options · object

Enable certain options associated with the payment methods.

​
warnings
ClientSessionWarningsAPIResponse · object

Warning messages to indicate missing information that are required for payment methods, checkout modules and other features; or when third-party services are unavailable.