Bootstrap de sesión del SDK: intercambia la clave por un client token

Antes de usar el SDK JS en el navegador, tu servidor debe intercambiar tu clave de API privada por un client token JWT de corta duración. Este token es lo que recibe el navegador — tu clave privada sin procesar nunca sale de tu servidor. Cada token está limitado a una sola sesión de checkout y expira después de 30 minutos.

Crea una sesión en tu servidor

Llama a POST /sdk/session desde tu backend con tu clave de API privada en el encabezado Authorization.

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

La respuesta incluye el clientToken y su vida útil en segundos:

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

Pasa el token al navegador

Entrega el clientToken a tu front-end. Los enfoques comunes incluyen:

JSON inline — insértalo en tu plantilla HTML cuando la página se renderiza en el servidor.
Respuesta de API — devuélvelo desde un endpoint ligero /api/checkout-session que tu SPA llama al cargar la página.

El navegador no necesita decodificar ni inspeccionar el token — lo pasa directamente a new TheriusSDK({ clientToken }).

Parámetros opcionales de la solicitud

Parámetro	Tipo	Descripción
`country`	string	Código de país ISO de dos letras. Requerido para una sesión de checkout completa con un `sessionId`.
`customerId`	string	Asocia la sesión con un comprador recurrente. Habilita las funciones de tarjeta guardada.
`amount`	object	Precompleta el monto de la sesión — útil para las hojas de pago de wallet.
`currency`	string	Código de moneda ISO de tres letras emparejado con `amount`.
`orderCode`	string	Tu referencia de orden interna, adjuntada a la sesión para la conciliación.
`cardOnFile`	object	Declara que este checkout de la sesión inicia un mandato de credencial almacenada — ver Suscripciones gestionadas por el comercio más abajo. Requiere `customerId`.

Suscripciones gestionadas por el comercio

Si gestionas tu propia facturación recurrente fuera de la API de Suscripciones de Therius — por ejemplo, un checkout único que debe establecer un mandato de tarjeta en archivo contra el que cobrarás tú mismo más adelante — pasa cardOnFile al crear la sesión, en lugar de configurar algo en el 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" }
      }'

Cuando cardOnFile está configurado:

El Checkout Widget omite por completo la casilla opcional “guardar mi tarjeta” y muestra en su lugar un aviso fijo (“Tu tarjeta se guardará para cargos futuros”) — no hay nada que el comprador deba aceptar, ya que declaraste la intención del lado del servidor.
El cargo resultante se tokeniza y se etiqueta con los campos de credencial almacenada indicados (usage/initiatedBy/type, ver Credenciales almacenadas) de forma incondicional, sin importar lo que envíe el navegador — el token de sesión firmado es la fuente de verdad, no el cuerpo de la solicitud.
customerId es obligatorio — debe existir un comprador al que atribuir la tarjeta guardada.

Si omites cardOnFile, la sesión se comporta exactamente como antes: el checkout sigue lo que indique la configuración “guardar mi tarjeta” (consentimiento de vault) del Checkout Builder, y cualquier tarjeta guardada resultante es una tarjeta en archivo simple, no un mandato recurrente.

Antes existía una casilla separada “Inicia una suscripción gestionada por el comercio” en el Checkout Builder. Se eliminó — ahora es una configuración por transacción y controlada por el servidor, en lugar de un indicador estático por configuración de checkout, así que un comprador nunca puede ver (ni suprimir) el estado de consentimiento incorrecto para una sesión determinada.

Inicializa el SDK en el navegador

Una vez que el navegador tiene el token, inicializa el SDK:

import { TheriusSDK } from '@therius/sdk'

const sdk = new TheriusSDK({ clientToken })

El SDK valida el token de inmediato. Si el token falta o está mal formado, TheriusSDK lanza una excepción de forma síncrona.

Vida útil del token

Los client tokens expiran después de 30 minutos. Crea un token fresco para cada nueva sesión de checkout — no caches ni reutilices tokens entre sesiones o cargas de página.

Nunca llames a POST /sdk/session desde el navegador. Requiere tu clave de API privada (prv_production_...). Exponer esa clave del lado del cliente permitiría a cualquiera crear sesiones y hacer cobros contra tu cuenta. Haz siempre esta llamada solo desde tu backend.

Referencia

Ver la referencia de la API POST /sdk/session para la referencia completa de campos, incluidos los códigos de error y las reglas de validación.

Descripción general

Recolección de tarjeta

Billeteras y más

Bootstrap de sesión del SDK: intercambia la clave por un client token

Crea una sesión en tu servidor

Pasa el token al navegador

Parámetros opcionales de la solicitud

Suscripciones gestionadas por el comercio

Inicializa el SDK en el navegador

Vida útil del token

Referencia

​Crea una sesión en tu servidor

​Pasa el token al navegador

​Parámetros opcionales de la solicitud

​Suscripciones gestionadas por el comercio

​Inicializa el SDK en el navegador

​Vida útil del token

​Referencia

Crea una sesión en tu servidor

Pasa el token al navegador

Parámetros opcionales de la solicitud

Suscripciones gestionadas por el comercio

Inicializa el SDK en el navegador

Vida útil del token

Referencia