> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Crea un token de SDK de corta duración
> Intercambia tu clave de API privada por un client token de corta duración para inicializar el SDK JS de Therius en el navegador de forma segura.
export const SchemaLangNote = ({lang}) => {
const text = ({
es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
})[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
return {text};
};
`POST /sdk/session` intercambia tu clave de API privada de comercio por un `clientToken` JWT de corta duración con un TTL de 30 minutos. Pasa el `clientToken` al navegador para inicializar `new TheriusSDK({ clientToken })`. Tu clave privada nunca llega al navegador — se queda en tu servidor, donde pertenece.
Llama a este endpoint solo desde tu servidor. Nunca lo llames desde JavaScript del navegador ni expongas tu clave de API privada al lado del cliente.
El cuerpo de la solicitud es completamente opcional — llámalo sin cuerpo para obtener un `clientToken` simple. Establece `country` (requerido en cuanto también estableces `amount`, `currency` u `orderCode`) para vincular la sesión y recibir un `sessionId`. Ver los paneles de parámetros y respuesta de arriba para la lista completa de campos.
El `clientToken` incrusta un hash HMAC-SHA256 de tu clave pública. Tu clave privada sin procesar nunca está presente en la carga del token y nunca llega al navegador.
Ver [Bootstrap de sesión](/sdk/session-bootstrap) en la pestaña JS SDK para saber cómo usar el `clientToken` del lado del cliente.
```bash cURL theme={"dark"}
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", "currency": "USD", "amount": 4999 }'
```
```json 200 OK theme={"dark"}
{
"clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 1800,
"sessionId": "sess_abc123",
"country": "US",
"amount": 4999,
"currency": "USD"
}
```
## OpenAPI
````yaml POST /sdk/session
openapi: 3.1.0
info:
title: Therius API
description: REST API for payments, subscriptions, and billing plans.
version: 1.0.0
servers:
- url: https://api.therius.io/v1
description: Production
- url: https://api-sandbox.therius.io/v1
description: Sandbox
security:
- bearerAuth: []
paths:
/sdk/session:
post:
tags:
- SDK
summary: Create a short-lived SDK token
operationId: createSdkSession
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
country:
type: string
description: >-
ISO 3166-1 alpha-2 code of the shopper country. Optional for
a bare clientToken; required if you also set `amount`,
`currency`, or `orderCode` (those create a bound checkout
session).
amount:
type: integer
description: >-
Locked amount in minor units. Omit to let the browser SDK
manage the amount.
currency:
type: string
description: >-
Locked ISO 4217 currency. Omit to let the browser SDK manage
it.
installments:
type: integer
description: Number of installments to offer. Defaults to 1.
orderCode:
type: string
description: Your order reference to attach to the resulting payment.
customerId:
type: string
description: >-
Your shopper identifier - enables saved-card retrieval and
the save-card checkbox for this session.
paymentCode:
type: string
description: >-
Pre-assigned Therius payment code, if you allocate them
yourself.
checkoutConfigId:
type: string
description: >-
UUID of a Checkout Builder configuration to bind to this
session.
cardOnFile:
allOf:
- $ref: '#/components/schemas/CardOnFile'
description: >-
Declares this session's checkout starts a stored-credential
mandate (e.g. `{"type": "recurring"}` for a merchant-managed
subscription you bill against yourself later). Requires
`customerId`. When set, the Checkout Widget shows a fixed
"card will be saved" disclosure instead of the optional
save-card checkbox, and the server forces tokenization +
this stored-credential tagging on the resulting charge
regardless of what the browser sends. Omit for a plain
checkout that just follows the Checkout Builder's save-card
setting.
responses:
'200':
description: SDK session token
content:
application/json:
schema:
type: object
properties:
clientToken:
type: string
description: >-
Short-lived JWT for the browser SDK. Pass as `Bearer` to
the SDK endpoints.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
expiresIn:
type: integer
description: Token lifetime in seconds.
example: 1800
defaultCheckoutConfigId:
type: string
description: >-
The merchant default Checkout Builder config, when no
`checkoutConfigId` was supplied.
sessionId:
type: string
description: >-
Checkout session ID - present when `country` created a
session.
country:
type: string
description: Echoed session country.
amount:
type: integer
description: Echoed locked amount.
currency:
type: string
description: Echoed locked currency.
cardOnFile:
allOf:
- $ref: '#/components/schemas/CardOnFile'
description: >-
Echoed stored-credential intent, present only when the
request set `cardOnFile`.
sdkIntegrity:
type: string
description: SRI hash for the SDK bundle, when available.
components:
schemas:
CardOnFile:
type: object
description: >-
Stored-credential (MIT/CIT) framework metadata for one-off payments.
Optional — Therius derives it from context when omitted. Not accepted on
subscription endpoints.
properties:
usage:
type: string
description: >-
Whether this charge establishes the stored-credential mandate
(`first`) or draws against an existing one (`subsequent`). Always
required alongside the other cardOnFile fields.
enum:
- first
- subsequent
initiatedBy:
type: string
description: >-
Who triggered this specific charge: the shopper live at checkout
(`cardholder`) or your billing engine unattended (`merchant`).
enum:
- cardholder
- merchant
type:
type: string
description: >-
The schedule shape of the mandate — independent of
`exceptionReason`. `recurring`: fixed-interval, usually fixed-amount
(subscriptions, membership dues). `installment`: a pre-agreed split
of one purchase into N charges. `unscheduled`: authorized in advance
but triggered by a merchant-defined event, including cards saved for
future use when the eventual charge pattern isn't known yet.
enum:
- recurring
- installment
- unscheduled
exceptionReason:
type: string
description: >-
Optional, MIT-only, and orthogonal to `type` — only set when this
particular charge falls into one of the scheme-defined exception
categories. `resubmission`: retrying a prior soft-declined charge
(insufficient funds, do-not-honor) for the same amount.
`incremental`: an authorization top-up on an existing mandate (e.g.
a hotel folio adds a room-service charge). `reauthorization`: a
fresh authorization because the original one expired before capture
(goods not yet shipped). `delayed_charge`: the final amount differs
from an earlier estimate/hold (car-rental extra mileage, a
restaurant tip). `no_show`: the cardholder didn't show up for a
reserved, guaranteed booking.
enum:
- resubmission
- incremental
- reauthorization
- delayed_charge
- no_show
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
prv_sandbox_xxx` (sandbox).
````