Sessões e tokens

Os endpoints do lado do servidor por trás do Bridge SDK — crie uma sessão de navegador, troque dados de cartão criptografados por uma referência de token de uso único e leia os detalhes não sensíveis de um token.

Estes são os endpoints que o Bridge SDK chama em seu nome. Uma sessão de navegador delimita o que o SDK pode fazer — para qual Merchant ele atua, a qual checkout está vinculado e quanto tempo dura. Um token é a referência de uso único (tok_…) que substitui os dados de cartão que seus servidores nunca veem.

A maioria das integrações nunca chama esses endpoints diretamente: o @tokeflow_com/bridge-js cuida do handshake da sessão e da tokenização para você. Nós os documentamos aqui porque eles definem o contrato — e porque fluxos orientados pelo servidor às vezes precisam criar uma sessão ou inspecionar os metadados não sensíveis de um token diretamente. Veja a visão geral do Bridge SDK para o caminho do lado do cliente.

Os dados de cartão são coletados dentro de iframes isolados e cross-origin e criptografados no navegador — eles nunca chegam aos seus servidores, e nem o PAN ou o CVC brutos. Esses endpoints só retornam as partes não sensíveis de um token (bandeira, últimos quatro dígitos, validade). Nunca tente enviar dados de cartão brutos para eles.

O objeto sessão

O que uma sessão expõe ao SDK depois de criada.

Campo	Tipo	Descrição
`sessionId`	string	ID da sessão.
`expiresAt`	string	Timestamp de expiração da sessão (ISO 8601).
`merchant`	object	Informações do Merchant.
`capabilities`	object	Capacidades de pagamento do Merchant.
`settings`	object	Configurações de tokenização do Merchant.
`sdk`	object	Informações de integridade do SDK.
`installmentsSupported`	boolean	Se o parcelamento é suportado pelo Merchant.
`installmentOptions`	object	Opções de parcelamento suportadas pelo Merchant, indexadas por método de pagamento.

Endpoints

POST`/api/v1/sessions`

Auth: Public key (X-Public-Key). Seguro no cliente — utilizável a partir do navegador.

Cria uma sessão de SDK para tokenização.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`sdkVersion`	string	Não	Versão do SDK usada pelo cliente.
`checkoutSessionId`	string	Não	Sessão de checkout a vincular a esta sessão de SDK. Validada contra o Merchant na criação; obrigatória para depois ler a sessão de checkout via GET /sessions/checkout.
`metadata`	object	Não	Metadados opcionais para armazenar com a sessão.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/sessions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "sdkVersion": "2.0.0",
    "checkoutSessionId": "cks_1234567890abcdef",
    "metadata": {
      "customerId": "cus_123",
      "checkoutId": "chk_456"
    }
  }'

Exemplo de resposta — 201

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2024-01-15T12:30:00.000Z",
  "merchant": {
    "id": "mrc_abc123",
    "name": "Acme Store",
    "organizationId": "org_xyz789"
  },
  "capabilities": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": true,
    "googlePay": true
  },
  "settings": {
    "allowedCardBrands": [
      "visa",
      "mastercard",
      "amex"
    ],
    "requireCvc": true,
    "requireCardholderName": true,
    "collectBillingAddress": true
  },
  "sdk": {
    "sriHash": "sha256-abcdef1234567890...",
    "sriExpiresAt": "2024-01-15T12:30:00.000Z"
  },
  "installmentsSupported": true,
  "installmentOptions": {
    "credit_card": {
      "min": 2,
      "max": 12
    },
    "pix": null
  }
}

GET`/api/v1/sessions/checkout`

Auth: Public key (X-Public-Key). Seguro no cliente — utilizável a partir do navegador.

Obtém o contexto completo de checkout da sessão de SDK — a sessão de checkout, os métodos de pagamento disponíveis e os cartões salvos do cliente.

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/sessions/checkout \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "checkout": {
    "id": "cks_a1b2c3d4e5",
    "merchantId": "mer_a1b2c3d4e5",
    "offerId": "ofr_a1b2c3d4e5",
    "customerId": "mcu_a1b2c3d4e5",
    "customerEmail": "jane@acme.com",
    "customerName": "Jane Doe",
    "selectedCurrency": "BRL",
    "status": "initiated",
    "externalSessionId": "sess_external_42",
    "expiresAt": "2026-05-20T18:00:00Z",
    "completedAt": "2026-05-20T17:32:11Z",
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z",
    "items": [
      {
        "id": "cki_a1b2c3d4e5",
        "checkoutSessionId": "cks_a1b2c3d4e5",
        "offerId": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 9900,
        "firstChargeAmount": 0,
        "quantity": 1,
        "installments": 1,
        "createdAt": "2026-05-19T12:00:00Z"
      }
    ]
  },
  "paymentMethods": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": false,
    "googlePay": false,
    "cardBrands": [
      "visa",
      "mastercard"
    ],
    "installmentsSupported": true,
    "installmentOptions": {
      "credit_card": {
        "min": 1,
        "max": 12
      }
    }
  },
  "savedInstruments": [
    {
      "id": "pi_a1b2c3d4e5",
      "instrumentType": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2030
    }
  ]
}

POST`/api/v1/sessions/:sessionId/payment-instruments`

Auth: Public key (X-Public-Key). Seguro no cliente — utilizável a partir do navegador.

Verifica um cartão (zero-dollar / SetupIntent) e o registra em arquivo para futuras cobranças iniciadas pelo Merchant.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`tokenId`	string	Sim	A referência de enrollment criptografada de uso único (`tok_…`) do Bridge SDK a verificar e salvar.
`customerId`	string	Não	id do cliente Tokeflow (cust_*) ao qual o cartão pertence. Recorre ao cliente do checkout vinculado.
`currency`	string	Não	Moeda ISO 4217 para o roteamento de verificação. Recorre à moeda do checkout vinculado.
`country`	string	Não	País ISO 3166-1 alpha-2. Recorre ao país do Merchant.
`connectorId`	string	Não	Verifica contra um conector específico; caso contrário, é roteado.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/sessions/ses_8c3a5d17/payment-instruments \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": "tok_8f3c2a1b9d4e",
    "customerId": "cust_2f9a71d4",
    "currency": "BRL",
    "country": "BR",
    "connectorId": "conn_a1b2c3d4"
  }'

Exemplo de resposta — 201

{
  "verified": true,
  "paymentInstrumentId": "string",
  "status": "active",
  "brand": "string",
  "last4": "string",
  "expMonth": 1,
  "expYear": 1,
  "reason": "requested_by_customer"
}

POST`/api/v1/sessions/:sessionId/refresh`

Auth: Public key (X-Public-Key). Seguro no cliente — utilizável a partir do navegador.

Renova a sessão de SDK.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`sessionId`	string	Sim	—

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/sessions/ses_8c3a5d17/refresh \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2024-01-15T12:30:00.000Z",
  "merchant": {
    "id": "mrc_abc123",
    "name": "Acme Store",
    "organizationId": "org_xyz789"
  },
  "capabilities": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": true,
    "googlePay": true
  },
  "settings": {
    "allowedCardBrands": [
      "visa",
      "mastercard",
      "amex"
    ],
    "requireCvc": true,
    "requireCardholderName": true,
    "collectBillingAddress": true
  },
  "sdk": {
    "sriHash": "sha256-abcdef1234567890...",
    "sriExpiresAt": "2024-01-15T12:30:00.000Z"
  },
  "installmentsSupported": true,
  "installmentOptions": {
    "credit_card": {
      "min": 2,
      "max": 12
    },
    "pix": null
  }
}

POST`/api/v1/tokens`

Auth: Public key (X-Public-Key). Seguro no cliente — utilizável a partir do navegador.

Registra um token criado via SDK.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`encryptedCard`	object	Sim	Dados de cartão criptografados do Bridge SDK.
`metadata`	object	Sim	Metadados do cartão (não criptografados).
`purpose`	string	Não	Finalidade do token: `one_time` (padrão — uso único, expira em 30 minutos) ou `instrument_enrollment` (sem expiração; pode ser salvo como instrumento de pagamento). Respeitado apenas na tokenização standalone — uma sessão do SDK criada sem `checkoutSessionId`.
`save_card`	boolean	Não	Dentro de uma sessão de checkout de uma oferta avulsa, `true` emite um token `instrument_enrollment` para que o cartão possa ser salvo. Ignorado para ofertas recorrentes (sempre cadastradas) e fora de uma sessão de checkout.
`additionalMetadata`	object	Não	Metadados adicionais opcionais para armazenar com o token.

Como a finalidade é decidida

Contexto	`purpose` resultante
Sessão standalone (sem sessão de checkout vinculada)	O que você enviar; `one_time` quando omitido. `save_card` não tem efeito.
Sessão de checkout, oferta recorrente	Sempre `instrument_enrollment`.
Sessão de checkout, oferta avulsa	`instrument_enrollment` quando `save_card: true`, caso contrário `one_time`. Qualquer `purpose` enviado é ignorado.

A resposta ecoa a finalidade que foi de fato emitida. Confira: um token one_time é recusado por save_payment_instrument, por POST /merchants/:merchant_id/payment-instruments e por POST /sessions/:sessionId/payment-instruments. O Bridge SDK expõe os dois campos como saveCard e purpose em TokenizeOptions.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "encryptedCard": {
      "number": "<encrypted by the Bridge SDK>",
      "cvc": "<encrypted by the Bridge SDK>",
      "expiryMonth": "12",
      "expiryYear": "25",
      "name": "<encrypted by the Bridge SDK>"
    },
    "metadata": {
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "bin": "424242"
    },
    "purpose": "one_time",
    "save_card": true,
    "additionalMetadata": {
      "customerId": "cus_123",
      "source": "checkout"
    }
  }'

Exemplo de resposta — 201

{
  "tokenId": "tok_8f3c2a1b9d4e",
  "merchant_id": "mrc_123",
  "purpose": "instrument_enrollment",
  "last4": "4242",
  "card_brand": "visa",
  "exp_month": "12",
  "exp_year": "2028",
  "status": "active",
  "expires_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2025-11-28T12:00:00Z"
}

POST`/api/v1/payer-tokens`

Auth: Public key (X-Public-Key) e uma sessão do SDK (X-Session-Id). Seguro no cliente — utilizável a partir do navegador.

Registra o pagador de uma cobrança PIX ou boleto e devolve um token de pagador (ptk_…). O Bridge SDK o chama a partir de pix.tokenize() e boleto.tokenize(). Em seguida, seu servidor envia o token como payer_token_id em POST /transactions, então ele nunca manipula o CPF/CNPJ nem o endereço do pagador.

O pagador é enviado via TLS, e não criptografado no navegador, porque a Tokeflow precisa lê-lo para validá-lo e repassá-lo ao provedor. Ele é armazenado criptografado e excluído assim que o token é usado ou expira.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`payment_method`	string	Sim	`pix` ou `boleto`. O token só pode ser cobrado com este método.
`name`	string	Sim	Nome completo do pagador, até 200 caracteres.
`email`	string	Sim	E-mail do pagador.
`phone`	string	Não	Telefone em formato internacional, por exemplo `+5511999990000`.
`document`	string	Sim	CPF ou CNPJ; a pontuação é aceita. Os dígitos verificadores são conferidos. CNPJs alfanuméricos são aceitos.
`document_type`	string	Não	`cpf` ou `cnpj`, sem diferenciar maiúsculas e minúsculas. Inferido pelo tamanho do documento quando omitido.
`address`	object	Boleto	Endereço de cobrança. Obrigatório para boleto (`street`, `neighborhood`, `city`, `state`, `postal_code`; `number` e `complement` opcionais). Não é necessário para PIX. `state` é uma UF de duas letras; `postal_code` é um CEP, `01310-100` ou `01310100`.

Exemplo de resposta — 201 Created

{
  "tokenId": "ptk_abc123",
  "type": "boleto",
  "document_type": "cpf",
  "document_last_digits": "25",
  "status": "active",
  "expires_at": "2026-10-26T12:30:00.000Z",
  "created_at": "2026-10-26T12:00:00.000Z"
}

Regra	Detalhe
Validade	Uso único; expira 30 minutos após a criação. Uma cobrança que falha também consome o token — colete o pagador novamente para tentar de novo.
Sessão de checkout	Quando a sessão do SDK está vinculada a uma sessão de checkout, o token só pode ser cobrado com aquele `checkout_session_id`.
Erros de campo	`400` com `details` indicando cada campo ausente ou inválido.

GET`/api/v1/tokens/:tokenId`

OrgMerchant

Auth: Organization key (com merchant_id) ou Merchant key.

Recupera os detalhes do token.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`tokenId`	string	Sim	—

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/tokens/tok_8f3c2a1b9d4e \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "tokenId": "tok_8f3c2a1b9d4e",
  "merchant_id": "mrc_123",
  "purpose": "instrument_enrollment",
  "last4": "4242",
  "card_brand": "visa",
  "exp_month": "12",
  "exp_year": "2028",
  "status": "active",
  "expires_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2025-11-28T12:00:00Z"
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTP	`type`	Causa típica
`400`	`validation_error`	Campo obrigatório ausente, ou uma operação que o estado atual não permite.
`401`	`authentication_error`	Chave de API ausente ou inválida.
`403`	`authorization_error`	A chave não tem o escopo necessário.
`404`	`not_found_error`	O recurso não existe ou não pertence a esta entidade.
`429`	`rate_limit_error`	Limite de taxa excedido — recue exponencialmente.

Veja Erros para o catálogo completo.

Sessões e tokens

O objeto sessão

Endpoints

POST`/api/v1/sessions`

GET`/api/v1/sessions/checkout`

POST`/api/v1/sessions/:sessionId/payment-instruments`

POST`/api/v1/sessions/:sessionId/refresh`

POST`/api/v1/tokens`

Como a finalidade é decidida

POST`/api/v1/payer-tokens`

GET`/api/v1/tokens/:tokenId`

Erros

Relacionados

Nesta página

Sessões e tokens

O objeto sessão

Endpoints

POST/api/v1/sessions

GET/api/v1/sessions/checkout

POST/api/v1/sessions/:sessionId/payment-instruments

POST/api/v1/sessions/:sessionId/refresh

POST/api/v1/tokens

Como a finalidade é decidida

POST/api/v1/payer-tokens

GET/api/v1/tokens/:tokenId

Erros

Relacionados

Nesta página

POST`/api/v1/sessions`

GET`/api/v1/sessions/checkout`

POST`/api/v1/sessions/:sessionId/payment-instruments`

POST`/api/v1/sessions/:sessionId/refresh`

POST`/api/v1/tokens`

POST`/api/v1/payer-tokens`

GET`/api/v1/tokens/:tokenId`