SDK Session Bootstrap: Exchange Key for Client Token

Before using the JS SDK in the browser, your server must exchange your private API key for a short-lived JWT client token. This token is what the browser receives — your raw private key never leaves your server. Each token is scoped to a single checkout session and expires after 30 minutes.

Create a session on your server

Call POST /sdk/session from your backend with your private API key in the Authorization header.

curl -X POST https://api.therius.io/v1/sdk/session \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "customer-42", "country": "US" }'

The response includes the clientToken and its lifetime in seconds:

{
  "clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 1800
}

Pass the token to the browser

Deliver clientToken to your front-end. Common approaches include:

Inline JSON — embed it in your HTML template when the page is server-rendered.
API response — return it from a lightweight /api/checkout-session endpoint that your SPA calls on page load.

The browser does not need to decode or inspect the token — it passes it directly to new TheriusSDK({ clientToken }).

Optional request parameters

Parameter	Type	Description
`country`	string	Two-letter ISO country code. Required for a full checkout session with a `sessionId`.
`customerId`	string	Associates the session with a returning shopper. Enables saved-card features.
`amount`	object	Pre-fills the session amount — useful for wallet payment sheets.
`currency`	string	Three-letter ISO currency code paired with `amount`.
`orderCode`	string	Your internal order reference, attached to the session for reconciliation.
`cardOnFile`	object	Declares this session’s checkout starts a stored-credential mandate — see Merchant-managed subscriptions below. Requires `customerId`.
`billingAddress`	object	The payer’s billing address, if you already know it: `address1` (street and number), `address2` (neighborhood), `city`, `state`, `postalCode`. The Checkout Widget prefills the matching fields from it (and skips them when the merchant chose Required, hidden if in session in the Checkout Builder; the card form skips the address only when the session holds `address1`, `city`, `state`, `postalCode` and `countryCode`), and a purchase that carries no address of its own is filled in from it. Boleto requires an address to register the voucher.
`shopper`	object	The payer’s data, if you already know it: `name`, `email`, `phone` and `document` (`{ "type": "CPF", "number": "..." }`). Same behavior as `billingAddress`: the widget prefills the matching fields of every payment method, skips a field the merchant set to Required, hidden if in session (card form: the email), and a purchase fills whatever it left blank from it. A value the shopper typed always wins. These are defaults, not locks. Requires `country`.
`deliveryAddress`	object	The shipping address (same shape as `billingAddress`), filled into a purchase that carries none of its own. Requires `country`.

Merchant-managed subscriptions

If you run your own recurring billing outside the Therius Subscriptions API — for example, a one-time checkout that should establish a card-on-file mandate you bill against yourself later — pass cardOnFile when creating the session, instead of configuring anything in the Checkout Builder:

curl -X POST https://api.therius.io/v1/sdk/session \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "customerId": "customer-42",
        "country": "US",
        "cardOnFile": { "type": "recurring" }
      }'

When cardOnFile is set:

The Checkout Widget skips the optional “save my card” checkbox entirely and shows a fixed disclosure (“Your card will be saved for future charges”) instead — there is nothing for the shopper to opt into, since you already declared the intent server-side.
The resulting charge is tokenized and tagged with the given stored-credential fields (usage/initiatedBy/type, see Stored Credentials) unconditionally, regardless of anything the browser sends — the signed session token is the source of truth, not the request body.
customerId is required — there must be a shopper to attribute the saved card to.

If you omit cardOnFile, the session behaves exactly as before: the checkout follows whatever the Checkout Builder’s “save my card” (vault-consent) setting says, and any resulting saved card is a plain card-on-file, not a recurring mandate.

There used to be a separate “Starts a merchant-managed subscription” checkbox in the Checkout Builder. It has been removed — this is now a per-transaction, server-controlled setting instead of a static per-checkout-config flag, so a shopper can never see (or suppress) the wrong consent state for a given session.

Load the SDK script with integrity checking

The session response also names the current release of the SDK script:

{
  "clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 1800,
  "sdk": {
    "version": "da5714d16d1f",
    "url": "https://api.therius.io/v1/sdk/js/v/da5714d16d1f",
    "integrity": "sha384-vD7RDhRnjB/DgxdKVQ1RFFSG33cOwn3rAwmYe87N1FJh0vcAF3khur6aqvp1WlL",
    "crossorigin": "anonymous"
  }
}

Each time your server renders the checkout page, write the script tag from these values:

<script src="{sdk.url}" integrity="{sdk.integrity}" crossorigin="anonymous"></script>

url always serves exactly the bytes that integrity describes, so the browser refuses to run anything else, such as a script altered by a compromised CDN, proxy, or browser extension. When Therius ships a fix, new sessions name the new release and you change nothing.

Do not hardcode the version or the hash. Read them from every session response.
Do not cache the rendered page for longer than the token lifetime (30 minutes). Therius keeps recent releases available so pages that are already rendered keep working, but a retired release answers 410 Gone and the checkout does not load until the page is rendered again. For a security fix, Therius can retire a release immediately.
The lazy-loaded parts (wallet buttons, Click to Pay) load from the same release and are checked against hashes carried inside the main script. There is nothing to configure.

If you cannot render the page on your server (for example, a static page), https://api.therius.io/v1/sdk/js always serves the latest release. It has no integrity check, so list it in your Content Security Policy script-src and in your script inventory, and monitor changes to your own page. Use the same URL when the session response has no sdk field. These measures support, but do not by themselves satisfy, the payment page script requirements of PCI DSS (6.4.3 and 11.6.1) for your page.

Initialize the SDK in the browser

Once the browser has the token, initialize the SDK:

import { TheriusSDK } from '@therius/sdk'

const sdk = new TheriusSDK({ clientToken })

The SDK validates the token immediately. If the token is missing or malformed, TheriusSDK throws synchronously.

Token lifetime

Client tokens expire after 30 minutes. Create a fresh token for each new checkout session — do not cache and reuse tokens across sessions or page loads.

Never call POST /sdk/session from the browser. It requires your private API key (prv_production_...). Exposing that key client-side would allow anyone to create sessions and make charges against your account. Always make this call from your backend only.

Reference

See the POST /sdk/session API reference for the full field reference, including error codes and validation rules.

Overview

Card Collection

Wallets & More

SDK Session Bootstrap: Exchange Key for Client Token

Create a session on your server

Pass the token to the browser

Optional request parameters

Merchant-managed subscriptions

Load the SDK script with integrity checking

Initialize the SDK in the browser

Token lifetime

Reference

​Create a session on your server

​Pass the token to the browser

​Optional request parameters

​Merchant-managed subscriptions

​Load the SDK script with integrity checking

​Initialize the SDK in the browser

​Token lifetime

​Reference

Create a session on your server

Pass the token to the browser

Optional request parameters

Merchant-managed subscriptions

Load the SDK script with integrity checking

Initialize the SDK in the browser

Token lifetime

Reference