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`.
`billingAddress`	object	La dirección de facturación del pagador, si ya la conoces: `address1` (calle y número), `address2` (barrio), `city`, `state`, `postalCode`. El Checkout Widget rellena los campos correspondientes (y los omite cuando el comercio eligió Obligatorio, salvo si viene en la sesión en el Checkout Builder), y un pago que no incluya dirección propia se completa con ella. Boleto requiere una dirección para registrar el voucher.
`shopper`	object	Los datos del pagador, si ya los conoces: `name`, `email`, `phone` y `document` (`{ "type": "CPF", "number": "..." }`). Mismo comportamiento que `billingAddress`: el widget rellena los campos de cada método de pago, omite el campo que el comercio configuró como Obligatorio, salvo si viene en la sesión, y el pago completa lo que haya quedado en blanco. Un valor escrito por el comprador siempre prevalece. Son valores por defecto, no bloqueos. Requiere `country`.
`deliveryAddress`	object	La dirección de envío (misma forma que `billingAddress`), que se completa en un pago que no incluya una propia. Requiere `country`.

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.

Carga el script del SDK con verificación de integridad

La respuesta de la sesión también indica la versión actual del script del SDK:

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

Cada vez que tu servidor renderice la página de checkout, escribe la etiqueta del script con estos valores:

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

url siempre sirve exactamente los bytes que describe integrity, así que el navegador se niega a ejecutar cualquier otro contenido, por ejemplo un script alterado por un CDN, un proxy o una extensión del navegador comprometidos. Cuando Therius publica una corrección, las sesiones nuevas indican la versión nueva y tú no cambias nada.

No fijes la versión ni el hash en tu código. Léelos en cada respuesta de sesión.
No guardes en caché la página renderizada por más tiempo que la vida del token (30 minutos). Therius mantiene disponibles las versiones recientes para que las páginas ya renderizadas sigan funcionando, pero una versión retirada responde 410 Gone y el checkout no carga hasta que se vuelva a renderizar la página. Ante una corrección de seguridad, Therius puede retirar una versión de inmediato.
Las partes de carga diferida (botones de wallet, Click to Pay) se cargan de la misma versión y se verifican con hashes incluidos en el script principal. No hay nada que configurar.

Si no puedes renderizar la página en tu servidor (por ejemplo, una página estática), https://api.therius.io/v1/sdk/js siempre sirve la versión más reciente. No tiene verificación de integridad, así que inclúyela en el script-src de tu Content Security Policy y en tu inventario de scripts, y vigila los cambios en tu propia página. Usa la misma URL cuando la respuesta de la sesión no incluya el campo sdk. Estas medidas apoyan los requisitos de scripts de la página de pago de PCI DSS (6.4.3 y 11.6.1) para tu página, pero por sí solas no los cumplen.

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

Carga el script del SDK con verificación de integridad

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

​Carga el script del SDK con verificación de integridad

​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

Carga el script del SDK con verificación de integridad

Inicializa el SDK en el navegador

Vida útil del token

Referencia