Changelog

Este é o registro contínuo das mudanças na plataforma Tokeflow — a API REST e o Bridge SDK. As entradas são listadas das mais recentes para as mais antigas, cada uma datada e agrupada por Adicionado, Alterado e Corrigido.

A Tokeflow é a camada de orquestração por trás da sua plataforma: os formatos de API e SDK documentados nesta referência são estáveis, e nós os evoluímos com cuidado. A maioria das versões é aditiva — novos campos, novos valores de enum, novos endpoints — e essas podem surgir dentro da versão principal atual (v1) a qualquer momento. Construa clientes que ignorem campos desconhecidos para que mudanças aditivas nunca o quebrem.

Como ler este changelog

Cada entrada indica se ela afeta a API, o SDK ou ambos.

---

2026-10-26 — Boleto, tokens de pagador para PIX e boleto, limites de taxa por classe de rota

Os pagadores de PIX e boleto agora podem ser coletados no navegador e cobrados por referência, o boleto chega ao Bridge SDK e os limites de taxa passam a ser definidos por tipo de rota. Todas as mudanças de API são retrocompatíveis.

Adicionado

REST API v1 (API)

• Tokens de pagador — POST /payer-tokens registra o pagador de uma cobrança PIX ou boleto (nome, e-mail, CPF/CNPJ e, para boleto, o endereço de cobrança) e devolve um ptk_… de uso único que expira após 30 minutos. Cobre-o com o novo payer_token_id em POST /transactions, para que seu servidor nunca manipule o documento nem o endereço do pagador. Um token inutilizável é recusado com 400 INVALID_PAYER_TOKEN. Veja Pagadores de PIX e boleto.
• Opções de boleto — boleto.expires_in_days (1–30, padrão 3) em POST /transactions; um vencimento que cai em fim de semana passa para o próximo dia útil.
• Instruções de pagamento do boleto — digitable_line junto com barcode, boleto_url e due_date (horário de Brasília, após o adiamento de fim de semana). Veja Métodos assíncronos.
• Capacidade boleto na sessão do SDK e no paymentMethods do contexto de checkout — true apenas quando um conector para o qual o merchant roteia boleto consegue cobrar um.

Bridge SDK 2.8.0 e 2.8.1 (SDK)

• Boleto — tokeflow.boleto.tokenize(), 'boleto' em getAvailablePaymentMethods() / useAvailablePaymentMethods() e o componente React <BoletoInstructions>. Veja Boleto.
• Novos tipos BoletoToken, PixTokenizeParams, BoletoTokenizeParams, PaymentInstructions, PixInstructions, BoletoInstructions e o código de erro INVALID_DOCUMENT. AvailablePaymentMethod ganha 'boleto' — um switch exaustivo sobre ele precisa de um novo case.

Alterado

• Limites de taxa por classe de rota (API): os limites agora são contados por chave e por rota em janelas de 60 segundos, com um teto definido pelo tipo de rota — 600 requisições por minuto para rotas de pagamento e de leitura, 1.200 para eventos de checkout (mais um limite por sessão), 600 para rotas do Bridge SDK (mais um limite por IP) e 60 para a verificação de cartão do SDK; as demais rotas mantêm 100. Um 429 agora traz os cabeçalhos Retry-After e X-RateLimit-* descrevendo o orçamento que o bloqueou. Limites maiores podem ser concedidos por chave — entre em contato com a equipe da Tokeflow. Veja Limites de taxa.
• pix.tokenize() (SDK 2.8.0): devolve um token de pagador (ptk_…) que a API consegue cobrar com payer_token_id; email agora é obrigatório, document aceita CPF ou CNPJ, e o token ganha documentType, documentLastDigits e expiresAt (cpfLastDigits está obsoleto). Atualize para a 2.8.0 para usar PIX: versões anteriores devolviam um token que não podia ser cobrado. Veja PIX.
• Associação de clientes (API): o e-mail de um token de pagador sozinho nunca vincula uma cobrança a um cliente existente; envie customer_id, ou o mesmo e-mail a partir do seu servidor.

Corrigido

• Concorrência entre captura e cancelamento (API): uma captura e um cancelamento na mesma autorização não podem mais ter efeito os dois. A chamada que perde responde 409 (conflict_error); leia a transação de volta em vez de tentar de novo. Veja Captura.
• Bridge SDK 2.7.1: o pacote 2.7.0 publicado continha o build da 2.6.0, sem savedCardCheckoutEnabled e SavedInstrument.reusable. Use a 2.7.1 ou posterior.
• Bridge SDK 2.8.1: o entry de React importa o core em vez de embutir uma cópia, então instanceof TokeflowError funciona entre os dois entries e o bundle de React fica cerca de 80% menor.

---

2026-10-09 — Motivos de recusa, checkout com cartão salvo, modo produção/teste

Toda tentativa que falha agora diz por que falhou em uma única palavra neutra em relação ao provedor, cartões salvos podem pagar uma sessão de checkout e toda transação informa se rodou com credenciais de produção ou de teste. Todas as mudanças são retrocompatíveis.

Adicionado

REST API v1 (API)

• Motivos de recusa — decline_reason em cada entrada da linha do tempo e em GET /transactions/:id/attempts, e no envelope de erro dos erros de pagamento que tenham um. Os códigos de recusa de todos os provedores são mapeados para um único vocabulário (insufficient_funds, card_expired, do_not_honor, other, …), de modo que a mesma palavra significa a mesma coisa qualquer que seja o conector que respondeu. A lista só cresce; veja Motivos de recusa.
• Checkout com cartão salvo — credential_on_file: true com payment_instrument_id agora pode pagar um checkout_session_id: a sessão fornece valor, moeda e cliente, e uma oferta recorrente inicia sua assinatura no conector que guarda a credencial do cartão. Controlado pelo novo opt-in de merchant saved_card_checkout_enabled (desativado por padrão) no objeto de merchant e em PATCH /merchants/:id.
• mode no objeto de transação — live ou test, conforme o conector da tentativa final; null quando a cobrança foi recusada antes do roteamento.
• payment_provider_id no objeto conector, para que você consiga ler o provedor de uma conexão mesmo depois que ele deixar de ser listado como ativo.

Bridge SDK (SDK)

• O checkout com cartão salvo está no ar. savedCardCheckoutEnabled e SavedInstrument.reusable (SDK 2.7.1+) agora retornam valores reais assim que o merchant faz o opt-in; não são mais reservados. Use o SDK 2.7.1 ou posterior — o pacote 2.7.0 publicado continha um build mais antigo.

Dashboard

• Os pedidos exibem um selo live/test, podem ser filtrados por mode, e as tentativas que falharam mostram seu motivo de recusa ao lado do código próprio do provedor. Veja Pedidos do Merchant.

Alterado

• Uma única política de roteamento para recusas (API): o motivo de recusa agora decide como uma recusa é tratada, de forma idêntica para todos os provedores — quais recusas iniciadas pelo cliente são retentadas e encadeadas em cascata, e quais interrompem a cobrança. Nas renovações de assinatura, uma renovação nunca é retentada dentro da requisição; só um motivo que diz que o cartão nunca mais poderá ser cobrado cancela a assinatura, e todas as outras recusas vão para dunning.
• Cobranças sem resposta do provedor (API): quando um provedor não dá veredito sobre uma cobrança de cartão, a transação permanece pending sem cascata enquanto a Tokeflow apura o resultado, e a sessão de checkout dela é liquidada quando o status final chega. Mais falhas de provedor agora são reconhecidas como "sem resposta" em vez de recusas.
• Credenciais de conector recusadas (API): uma renovação roteada para um conector cujas credenciais o provedor confirma que recusa é colocada em uma retenção de cobrança em vez de ir para dunning, e salvar novas credenciais a libera. Veja Credenciais recusadas.
• Provedores inativos (API): um conector cujo provedor de pagamento está inativo pode ser desativado, renomeado ou ter as credenciais rotacionadas, mas não pode ser reativado.
• gateway_fee (API): agora é a taxa conforme informada pelo provedor, preenchida depois quando o provedor a informa após a cobrança.
• Configurações de merchant que podem ser sobrescritas (API): network_tokens_enabled e saved_card_checkout_enabled são escolha do próprio merchant; a Tokeflow pode definir qualquer um deles para uma organization ou um merchant, e essa configuração prevalece. Veja Configurações que a Tokeflow pode sobrescrever.

Corrigido

• Datas de cobrança de assinaturas (API): ciclos mensais e mais longos não pulam mais um mês quando o dia âncora é 29, 30 ou 31; a renovação cai no último dia do mês. current_period_end agora é sempre igual à data de renovação ancorada, e uma troca de plano mantém a âncora existente. Veja Datas de cobrança.

---

2026-09-24 — Cobranças em um clique, dois novos provedores, parcelamento por conector

Cartões salvos agora podem ser cobrados de novo com um único clique, cartões podem ser salvos durante uma compra avulsa e dois provedores de pagamento entram no catálogo. Todas as mudanças são retrocompatíveis.

Adicionado

REST API v1 (API)

• Cobranças em um clique com credencial armazenada — credential_on_file: true em POST /transactions cobra um payment_instrument_id salvo com a credencial do provedor guardada no cadastro: sem dados de cartão, sem CVV, sem sessão de checkout. A cobrança é fixada no conector que guarda a credencial, é sempre capturada e é registrada como um pedido unscheduled iniciado pelo cliente. Leia o guia: Upsells e downsells em um clique.
• Salvar um cartão ao cobrar — save_payment_instrument: true em POST /transactions cadastra o cartão por trás de card_ciphertext_id como um instrumento de pagamento antes da cobrança e guarda a credencial reutilizável do provedor para cobranças em um clique posteriores. Exige um ciphertext emitido com purpose=instrument_enrollment.
• payer_ip em POST /transactions — o endereço IP do pagador, exigido por alguns provedores em cobranças com cartão. Recorre ao IP da sessão do Bridge SDK do pagador quando a cobrança pertence a uma sessão de checkout.
• Dois novos provedores de pagamento no catálogo, ambos com suporte a cobranças com credencial armazenada (um clique). A disponibilidade é habilitada por organização — entre em contato com a equipe da Tokeflow para a lista atual; os padrões de credenciais e as regras de webhook estão em Provedores de pagamento e Conectores.
• Parcelamento por conector — o catálogo de provedores agora expõe installment_config (a faixa que cada provedor suporta por método de pagamento), e o config.installments_enabled de um conector escolhe dentro dela: não definido aceita parcelas pedidas via API sem oferecê-las no checkout, true também as oferece no checkout, false as recusa. Veja Configuração do conector.
• Campos do catálogo de provedores — default_supported_card_brands e supported_currencies no objeto de provedor de pagamento.
• Opt-in de network tokens — network_tokens_enabled no objeto de merchant e em PATCH /merchants/:id. O provisionamento agora é uma escolha explícita por merchant, desligada por padrão; merchants que já usavam network tokens foram incluídos automaticamente.

Bridge SDK 2.6.0 e 2.7.0 (SDK)

• saveCard e purpose em TokenizeOptions — uma integração no navegador agora consegue emitir um ciphertext cadastrável: saveCard: true dentro de uma sessão de checkout de oferta avulsa, ou purpose: 'instrument_enrollment' na tokenização standalone. O CardToken retornado ecoa o purpose que o servidor de fato emitiu, e TokenPurpose é exportado. Veja Tokenização → Opções.
• savedCardCheckoutEnabled e SavedInstrument.reusable no contexto de checkout — reservados para o checkout com cartão salvo, que está em fase de lançamento; os dois retornam false até que ele seja habilitado para o seu merchant.

Alterado

• Cobrar um cartão salvo (API): payment_instrument_id sozinho agora é recusado com 400. Envie-o com credential_on_file: true (um clique) ou com um card_ciphertext_id novo (CVV redigitado). Veja Origens de cartão.
• POST /tokens (API): documentado como o purpose do token é decidido — dentro de uma sessão de checkout o servidor o deriva da oferta e de save_card e ignora um purpose enviado pelo cliente; a tokenização standalone o mantém.
• Conectores (API): has_webhook_secret é true para provedores que assinam webhooks com uma chave já presente em credentials; chaves desconhecidas em credentials são recusadas; uma chave cujo ambiente não corresponde a is_test_mode é rejeitada.

Corrigido

• O exemplo de POST /merchants/:merchant_id/payment-instruments enviava um endereço IP como card_ciphertext_id; agora mostra uma referência tok_….
• Os valores de exemplo de cartão criptografado em POST /tokens não mostram mais um formato bruto de ciphertext.

---

2026-09-04 — Reativação de assinatura e clareza de cobrança

Novos controles de assinatura e comportamento de cobrança mais claro na API REST e no Dashboard. Todas as mudanças são retrocompatíveis.

Adicionado

REST API v1 (API) e Dashboard

• Reativar uma assinatura — um novo endpoint que suspende um cancelamento agendado e mantém uma assinatura viva no seu plano, tanto na API pública quanto no Dashboard do merchant. É também o remédio quando um cliente tenta iniciar um plano que já possui.
• Atribuição de ator nas transições de assinatura: mudanças disparadas por admin passam a carregar um snapshot actor do usuário do Dashboard que as executou.
• Documentadas as retenções de cobrança (billing holds) e a regra de uma assinatura viva por plano no ciclo de vida de Assinaturas.

Alterado

• Trocar de oferta (API): após uma troca de plano, o billing_cycle passa a re-sincronizar com o ciclo da nova oferta, em vez de manter o valor anterior.
• Reembolsos (API): esclarecido que reembolsos pending contam para o saldo reembolsável e que um reembolso sem resultado definitivo do provedor permanece em dúvida — a transação continua refund_pending — em vez de ser liberado.
• Webhooks (API): documentada a janela completa de retentativas — um endpoint que falha em todas as tentativas é reprocessado ao longo de cerca de 26 horas antes de a entrega ser abandonada — e que cada entrega é carimbada no momento em que é liquidada.

---

2026-08-13 — Referência da API expandida

Uma grande atualização da documentação cobrindo mais da superfície /api/v1, além de uma nova seção Dashboards para os endpoints autenticados por sessão do Dashboard e do Portal do Cliente. Nenhum comportamento mudou — esta release documenta endpoints que já estavam no ar.

Adicionado

REST API v1 (API)

• Merchants (mrc_) — gerencie merchants e os membros da equipe dentro de uma organization.
• API Keys (ak_) — crie, liste, consulte escopos e revogue chaves de API programaticamente.
• Webhook Endpoints — registre endpoints, inspecione entregas e rotacione segredos de assinatura pela API.
• Sessions & Tokens (tok_) — os endpoints de sessão e tokenização do lado do servidor por trás do Bridge SDK.
• Connectors (conn_) e Routing Profiles — conecte provedores de pagamento e defina regras de roteamento inteligente e ordem de fallback.
• Payment Providers, Audit Logs e Health.
• Novos endpoints em recursos existentes: excluir um customer, criar um payment instrument e cancelar administrativamente uma subscription.

Dashboards (API)

• Documentamos os endpoints autenticados por sessão do Merchant Dashboard, do Organization Dashboard e do Customer Portal — as superfícies por trás do Tokeflow Dashboard e do portal self-service do cliente. Eles autenticam com uma sessão do Dashboard (JWT bearer) ou uma sessão de magic-link do portal, e não com chaves de API sk_/pk_.

Alterado

• A lista de grupos de recursos na visão geral da referência da API agora inclui os recursos recém-documentados.

2026-06-23 — API pública v1 e Bridge SDK

O primeiro lançamento público da plataforma Tokeflow: uma API REST estável e versionada e um SDK do lado do cliente para coletar dados de pagamento no navegador. Tudo nesta referência está disponível de forma geral a partir deste lançamento.

Adicionado

API REST v1 (API)

Toda a superfície /api/v1 está no ar em https://api.tokeflow.com. Um envelope consistente, um conjunto de convenções, em todos os provedores de pagamento que você conectar.

• Customers (cust_) — crie e gerencie pagadores, incluindo documentos (cpf, cnpj, passport, tax_id) e detalhes de contato.
• Checkout Sessions (cks_) — fluxos de checkout hospedados e incorporados com itens de linha, identificação do cliente e uma linha do tempo de eventos transmitida.
• Transactions (tx_) — crie, recupere, capture e cancele pagamentos nos métodos credit_card, debit_card, pix, boleto e wallet.
• Refunds (ref_) — reembolsos totais ou parciais contra transações capturadas.
• Orders (ord_) — registros de pedidos que agrupam transações nos fluxos de API, checkout e renovação.
• Subscriptions (sub_) — cobrança recorrente com ciclo de vida, dunning, pausa/retomada e mudanças de oferta.
• Payment Instruments (pi_) — métodos de pagamento salvos em arquivo para cobranças iniciadas pelo Merchant e cobranças repetidas.
• Catalog — famílias de produtos (pfa_), produtos (prd_), ofertas (ofr_), preços de ofertas (opr_) e transições de ofertas (oft_).

Autenticação e escopo de chaves (API)

• Chaves de API de Organization e Merchant. Cada chave tem escopo em exatamente uma entidade. Uma chave de Merchant infere seu merchant automaticamente; uma chave de Organization abrange todos os merchants na org e mira em um deles com o parâmetro merchant_id. Consulte Authentication.
• Chaves secretas e públicas. Chaves secretas (sk_…) autorizam chamadas servidor-a-servidor; chaves públicas (pk_…) são restritas a escopos seguros para o cliente e são seguras para enviar em código de navegador. As permissões seguem um modelo resource:action. Consulte Environments and keys.

Convenções da plataforma (API)

• Idempotência. Envie um cabeçalho Idempotency-Key (ou o campo de corpo idempotency_key) em mutações de criação e cobrança — notadamente POST /transactions — e as repetições retornam o resultado original em vez de duplicar. Consulte Idempotency and rate limits.
• Webhooks com entrega assinada. Notificações de eventos normalizadas e independentes de provedor, cada uma assinada com um cabeçalho X-Tokeflow-Signature (HMAC-SHA256) para que você possa verificar a autenticidade antes de agir. Consulte Webhooks.
• Envelopes, erros e paginação padrão. Um envelope success/data/meta consistente, um catálogo de erros estável e legível por máquina e paginação baseada em página em todos os endpoints de listagem. Consulte a visão geral da referência da API.

Bridge SDK (SDK)

O Bridge SDK @tokeflow_com/bridge-js coleta dados sensíveis de pagamento no navegador e os troca por uma referência de token de curta duração (tok_…) — os dados do cartão são criptografados no navegador e nunca tocam nos seus servidores. Consulte a visão geral do Bridge SDK.

• Coleta de cartão com elementos seguros pré-construídos e personalizáveis por tema. Consulte Elements e Tokenization.
• PIX, Apple Pay e Google Pay — todo método habilitado produz o mesmo tipo de referência de token. Consulte Payment methods.
• Contexto de checkout — leia os itens precificados, a moeda selecionada, os métodos habilitados e os instrumentos salvos de uma checkout session aberta. Consulte Checkout.
• Localização — pacotes en e pt-BR integrados com substituições de strings por elemento. Consulte Localization.
• Bindings de React — provider, hooks e componentes de elemento de primeira classe. Consulte React.
• Autenticação por chave pública — o SDK autentica apenas com uma chave publicável; as chaves secretas permanecem no seu servidor.

Versão em resumo

Próximos passos

• Quickstart — um pagamento de ponta a ponta.
• Visão geral da referência da API — URL base, autenticação, envelopes e convenções.
• Visão geral do Bridge SDK — colete e tokenize dados de pagamento no navegador.
• Webhooks — receba e verifique eventos assinados.