PRprimer
Client Session API

Create a client session

Changed on

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.

<b>Note:</b> 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.

<code>POST /client-session</code> does not have required fields as all fields are not always known when a client session is created. Use <code>PATCH /client-session</code> to update the parameters throughout the checkout session.

Client tokens expire after 24 hours.

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

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 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.

customerIdstring

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.

metadataobject

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.

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.

Example request

{
  "orderId": "order-abc",
  "currencyCode": "GBP",
  "amount": 1000,
  "order": {
    "countryCode": "FR,",
    "lineItems": [
      {
        "itemId": "shoe-123",
        "description": "Blue Shoe",
        "amount": 100,
        "quantity": 10
      }
    ]
  },
  "customerId": "customer-123",
  "customer": {
    "emailAddress": "john@primer.io"
  },
  "metadata": {
    "productType": "Shoes"
  },
  "paymentMethod": {
    "descriptor": "Purchase: Shoes",
    "paymentMethodType": "PAYMENT_CARD",
    "vaultOnSuccess": true,
    "vaultOn3DS": false,
    "options": {
      "PAYMENT_CARD": {
        "networks": {
          "VISA": {
            "surcharge": {
              "amount": 10
            }
          }
        }
      },
      "GOOGLE_PAY": {
        "surcharge": {
          "amount": 20
        }
      }
    },
    "authorizationType": "ESTIMATED"
  }
}

Response

Successful Response

clientTokenstring required

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.

clientTokenExpirationDatestring date-time required

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

orderIdstring

Your reference for the payment.

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.

customerIdstring

A unique identifier for your customer.

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

{
  "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,
    "vaultOn3DS": false,
    "options": {
      "PAYMENT_CARD": {
        "networks": {
          "VISA": {
            "surcharge": {
              "amount": 10
            }
          }
        },
        "captureVaultedCardCvv": true
      },
      "GOOGLE_PAY": {
        "surcharge": {
          "amount": 20
        }
      }
    },
    "authorizationType": "ESTIMATED"
  },
  "warnings": [
    {
      "type": "TAXJAR",
      "code": "MISSING_DATA",
      "message": "Shipping details are required for calculating tax."
    }
  ]
}

Changes

  • 6b60d7283338Revision changes
    • breaking

      removed the enum value MRO of the request property

    • breaking

      removed the enum value XAG of the request property

    • breaking

      removed the enum value XAU of the request property

    • breaking

      removed the enum value XBA of the request property

    • breaking

      removed the enum value XBB of the request property

    • breaking

      removed the enum value XBC of the request property

    • breaking

      removed the enum value XBD of the request property

    • breaking

      removed the enum value XDR of the request property

    • breaking

      removed the enum value XFU of the request property

    • breaking

      removed the enum value XPD of the request property

    • breaking

      removed the enum value XPT of the request property

    • breaking

      removed the enum value XSU of the request property

    • breaking

      removed the enum value XTS of the request property

    • breaking

      removed the enum value XUA of the request property

    • breaking

      the response's property type changed from object to array for status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      added the new EFTPOS enum value to the // response property for the response status

    • info

      added the new optional request property

    • info

      added the new EFTPOS enum value to the request property //

    • info

      added the new SLE enum value to the request property

    • info

      added the new STN enum value to the request property

    • info

      added the new VED enum value to the request property

    • info

      added the new VES enum value to the request property

    • info

      added the new XCG enum value to the request property

    • info

      added the new ZWG 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