Bootstrap de sessão do SDK: troque a chave por um client token

Antes de usar o SDK JS no navegador, o seu servidor precisa trocar a sua chave de API privada por um client token JWT de curta duração. Esse token é o que o navegador recebe — a sua chave privada bruta nunca sai do seu servidor. Cada token é limitado a uma única sessão de checkout e expira após 30 minutos.

Crie uma sessão no seu servidor

Chame POST /sdk/session do seu backend com a sua chave de API privada no cabeçalho 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" }'

A resposta inclui o clientToken e o tempo de vida dele em segundos:

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

Passe o token ao navegador

Entregue o clientToken ao seu front-end. As abordagens comuns incluem:

JSON inline — insira-o no seu template HTML quando a página é renderizada no servidor.
Resposta de API — devolva-o de um endpoint leve /api/checkout-session que a sua SPA chama ao carregar a página.

O navegador não precisa decodificar nem inspecionar o token — ele o passa diretamente para new TheriusSDK({ clientToken }).

Parâmetros opcionais da requisição

Parâmetro	Tipo	Descrição
`country`	string	Código de país ISO de duas letras. Obrigatório para uma sessão de checkout completa com um `sessionId`.
`customerId`	string	Associa a sessão a um comprador recorrente. Habilita os recursos de cartão salvo.
`amount`	object	Pré-preenche o valor da sessão — útil para as folhas de pagamento de carteira.
`currency`	string	Código de moeda ISO de três letras pareado com `amount`.
`orderCode`	string	A sua referência de pedido interna, anexada à sessão para a conciliação.
`cardOnFile`	object	Declara que o checkout desta sessão inicia um mandato de credencial armazenada — veja Assinaturas gerenciadas pelo lojista abaixo. Exige `customerId`.
`billingAddress`	object	O endereço de cobrança do pagador, se você já o conhece: `address1` (rua e número), `address2` (bairro), `city`, `state`, `postalCode`. O Checkout Widget preenche os campos correspondentes (e os omite quando o lojista escolheu Obrigatório, exceto se vier na sessão no Checkout Builder), e um pagamento sem endereço próprio é completado com ele. O Boleto exige endereço para registrar o título.
`shopper`	object	Os dados do pagador, se você já os conhece: `name`, `email`, `phone` e `document` (`{ "type": "CPF", "number": "..." }`). Mesmo comportamento do `billingAddress`: o widget preenche os campos de cada método de pagamento, omite o campo que o lojista configurou como Obrigatório, exceto se vier na sessão, e o pagamento completa o que ficou em branco. Um valor digitado pelo comprador sempre prevalece. São valores padrão, não bloqueios. Exige `country`.
`deliveryAddress`	object	O endereço de entrega (mesmo formato do `billingAddress`), preenchido em um pagamento que não traga um próprio. Exige `country`.

Assinaturas gerenciadas pelo lojista

Se você gerencia sua própria cobrança recorrente fora da API de Assinaturas do Therius — por exemplo, um checkout único que deve estabelecer um mandato de cartão em arquivo contra o qual você mesmo vai cobrar depois — envie cardOnFile ao criar a sessão, em vez de configurar algo no 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" }
      }'

Quando cardOnFile está definido:

O Checkout Widget pula completamente a caixa de seleção opcional “salvar meu cartão” e mostra em vez disso um aviso fixo (“Seu cartão será salvo para cobranças futuras”) — não há nada para o comprador optar, já que você já declarou a intenção no lado do servidor.
A cobrança resultante é tokenizada e marcada com os campos de credencial armazenada informados (usage/initiatedBy/type, veja Credenciais Armazenadas) incondicionalmente, independentemente do que o navegador enviar — o token de sessão assinado é a fonte da verdade, não o corpo da requisição.
customerId é obrigatório — precisa existir um comprador ao qual atribuir o cartão salvo.

Se você omitir cardOnFile, a sessão se comporta exatamente como antes: o checkout segue o que a configuração “salvar meu cartão” (consentimento de vault) do Checkout Builder disser, e qualquer cartão salvo resultante é um cartão em arquivo simples, não um mandato recorrente.

Antes existia uma caixa de seleção separada “Inicia uma assinatura gerenciada pelo lojista” no Checkout Builder. Ela foi removida — agora isso é uma configuração por transação e controlada pelo servidor, em vez de um indicador estático por configuração de checkout, então um comprador nunca consegue ver (nem suprimir) o estado de consentimento errado para uma determinada sessão.

Carregue o script do SDK com verificação de integridade

A resposta da sessão também informa a versão atual do script do SDK:

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

Toda vez que o seu servidor renderizar a página de checkout, escreva a tag do script com estes valores:

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

url sempre entrega exatamente os bytes que integrity descreve, então o navegador se recusa a executar qualquer outro conteúdo, como um script alterado por um CDN, um proxy ou uma extensão do navegador comprometidos. Quando o Therius publica uma correção, as novas sessões indicam a nova versão e você não muda nada.

Não fixe a versão nem o hash no seu código. Leia-os em cada resposta de sessão.
Não mantenha a página renderizada em cache por mais tempo do que a vida do token (30 minutos). O Therius mantém as versões recentes disponíveis para que as páginas já renderizadas continuem funcionando, mas uma versão retirada responde 410 Gone e o checkout não carrega até que a página seja renderizada novamente. Em caso de correção de segurança, o Therius pode retirar uma versão imediatamente.
As partes de carregamento sob demanda (botões de wallet, Click to Pay) são carregadas da mesma versão e verificadas com hashes incluídos no script principal. Não há nada a configurar.

Se você não consegue renderizar a página no seu servidor (por exemplo, uma página estática), https://api.therius.io/v1/sdk/js sempre entrega a versão mais recente. Ela não tem verificação de integridade, então inclua-a no script-src da sua Content Security Policy e no seu inventário de scripts, e monitore as mudanças na sua própria página. Use a mesma URL quando a resposta da sessão não trouxer o campo sdk. Essas medidas apoiam, mas por si sós não cumprem, os requisitos de scripts da página de pagamento do PCI DSS (6.4.3 e 11.6.1) para a sua página.

Inicialize o SDK no navegador

Assim que o navegador tem o token, inicialize o SDK:

import { TheriusSDK } from '@therius/sdk'

const sdk = new TheriusSDK({ clientToken })

O SDK valida o token de imediato. Se o token estiver ausente ou malformado, TheriusSDK lança uma exceção de forma síncrona.

Tempo de vida do token

Os client tokens expiram após 30 minutos. Crie um token novo para cada nova sessão de checkout — não faça cache nem reutilize tokens entre sessões ou carregamentos de página.

Nunca chame POST /sdk/session do navegador. Ela exige a sua chave de API privada (prv_production_...). Expor essa chave no lado do cliente permitiria que qualquer pessoa criasse sessões e fizesse cobranças contra a sua conta. Faça sempre essa chamada apenas do seu backend.

Referência

Veja a referência da API POST /sdk/session para a referência completa de campos, incluindo os códigos de erro e as regras de validação.

Visão geral

Coleta de cartão

Carteiras e mais

Bootstrap de sessão do SDK: troque a chave por um client token

Crie uma sessão no seu servidor

Passe o token ao navegador

Parâmetros opcionais da requisição

Assinaturas gerenciadas pelo lojista

Carregue o script do SDK com verificação de integridade

Inicialize o SDK no navegador

Tempo de vida do token

Referência

​Crie uma sessão no seu servidor

​Passe o token ao navegador

​Parâmetros opcionais da requisição

​Assinaturas gerenciadas pelo lojista

​Carregue o script do SDK com verificação de integridade

​Inicialize o SDK no navegador

​Tempo de vida do token

​Referência

Crie uma sessão no seu servidor

Passe o token ao navegador

Parâmetros opcionais da requisição

Assinaturas gerenciadas pelo lojista

Carregue o script do SDK com verificação de integridade

Inicialize o SDK no navegador

Tempo de vida do token

Referência