Como o Tokeflow funciona

O Tokeflow é a infraestrutura por trás da sua plataforma. Você conecta múltiplos provedores de pagamento uma única vez, aplica regras de roteamento inteligente e processa cada pagamento por meio de uma API única e normalizada — sob a sua própria marca.

O Tokeflow orquestra pagamentos. Ele não processa nem liquida fundos: autorização, captura e liquidação são realizadas pelos provedores de pagamento que você conecta. O Tokeflow fica na frente desses provedores e oferece a você um contrato consistente, roteamento inteligente, resiliência e uma trilha de auditoria unificada em todos eles.

Esta página explica as partes móveis e percorre, passo a passo, o que acontece quando um pagamento é feito.

Os componentes fundamentais

Quatro primitivas compõem quase tudo o que você constrói no Tokeflow.

API

A API REST em https://api.tokeflow.com é o núcleo do lado do servidor. Cada endpoint fica sob /api/v1 (versionamento por URI; a versão atual é v1). Seu backend se autentica com uma chave secreta (Authorization: Bearer sk_live_…) e usa a API para criar transações, capturar ou cancelar autorizações, emitir reembolsos, gerenciar o catálogo de produtos e ler resultados normalizados. As chaves têm escopo definido para uma Organization ou para um único Merchant, e toda resposta é envolvida em um envelope consistente de sucesso ou erro. Consulte Autenticação.

Bridge SDK

O Bridge SDK é o complemento do lado do navegador para a API. Ele renderiza campos seguros e coleta dados sensíveis de cartão sem que esses dados jamais toquem seus servidores. Os campos seguros do Tokeflow são executados dentro de iframes isolados e de origem cruzada; os dados do cartão são criptografados no navegador e nunca chegam à sua infraestrutura. O SDK se autentica com uma chave pública (pk_live_…), que é segura para expor no código do cliente, e retorna uma referência de curta duração que seu backend usa para cobrar o cartão. Consulte o Bridge SDK.

Checkout Sessions

Uma Checkout Session modela um fluxo de compra hospedado ou embutido. Ela rastreia o cliente, os itens, a moeda selecionada e o ciclo de vida da experiência de compra — de initiated, passando por customer_identified e payment_pending, até completed. As sessões emitem eventos granulares aos quais você pode reagir e, quando uma sessão é cobrada, o Tokeflow executa a mesma orquestração de uma transação direta pela API. Use sessões quando quiser que o Tokeflow coordene a experiência do topo do funil; use a API de transações diretamente quando sua plataforma já for responsável pela interface de checkout. Consulte Checkout Sessions.

Webhooks

Webhooks são a forma como o Tokeflow informa aos seus sistemas o que aconteceu. Toda mudança de estado significativa — uma transação sendo autorizada, um reembolso sendo bem-sucedido, um chargeback sendo aberto, uma assinatura entrando em cobrança de inadimplência — é entregue como um evento assinado e normalizado ao endpoint que você registra durante o onboarding. Como o Tokeflow normaliza notificações específicas de cada provedor em um único schema, seu handler de webhook não muda quando você adiciona ou troca de provedor. Todo payload é assinado com X-Tokeflow-Signature para que você possa verificar a autenticidade. Consulte Webhooks.

Anatomia de um pagamento

Aqui está o caminho de ponta a ponta de um pagamento com cartão, do navegador do cliente até um resultado normalizado e um webhook.

1. Colete o cartão no lado do cliente. Seu frontend monta os campos seguros do Bridge SDK. O cliente digita os dados do cartão em iframes isolados e de origem cruzada. Os dados são criptografados no navegador e nunca tocam seus servidores. O SDK retorna uma referência de curta duração ao cartão criptografado.
2. Envie a referência ao seu backend. Seu frontend envia a referência (e o contexto do pedido) ao seu próprio backend pelo seu canal normal. Nenhum dado de cartão em texto puro está envolvido.
3. Crie a transação. Seu backend chama POST /api/v1/transactions com uma chave secreta, o valor em unidades menores, a moeda e a referência do cartão. Alternativamente, uma Checkout Session é cobrada, o que dispara o mesmo fluxo. Envie uma Idempotency-Key para que as retentativas nunca gerem cobrança em duplicidade.
4. O Tokeflow seleciona um provedor. As regras de roteamento inteligente escolhem o melhor provedor para esta transação com base em atributos como país, moeda, método de pagamento e valor.
5. Cascata em recusas leves. Se o provedor escolhido retornar uma recusa leve (uma falha passível de nova tentativa, como um timeout do emissor ou um "do not honor" temporário), o Tokeflow automaticamente cascateia para o próximo provedor elegível na rota. Recusas rígidas (como cartão roubado ou cartão inválido) não são repetidas.
6. Retorne um resultado normalizado. O Tokeflow retorna um único objeto de transação agnóstico ao provedor. O campo status informa o desfecho, e o array timeline registra cada tentativa — incluindo quais provedores foram tentados e por que cada um teve sucesso ou falhou.
7. Emita webhooks. O Tokeflow emite eventos de webhook assinados e normalizados para as mudanças de estado resultantes, para que seus sistemas subsequentes fiquem sincronizados sem polling.

Autorização vs. captura

Pagamentos com cartão separam duas etapas: autorização reserva os fundos no cartão do cliente, e captura efetivamente os coleta. O Tokeflow permite que você faça as duas de uma vez ou as divida.

• Autorizar e capturar juntos. Defina capture: true em POST /api/v1/transactions. Em caso de sucesso, a transação chega ao estado authorized e os fundos são coletados em uma única etapa. Este é o padrão para a maioria das compras de execução única.
• Autorizar agora, capturar depois (pré-autorização). Defina capture: false. Em caso de sucesso, a transação chega ao estado pre_authorized — os fundos são reservados, mas não coletados. Mais tarde, você os coleta com uma chamada de captura ou libera a reserva com um cancelamento (void).

Esse modelo de duas etapas é útil quando o valor final ou o cumprimento do pedido não é conhecido no momento da compra — por exemplo, reservar um valor no momento do pedido e capturá-lo assim que o pedido for enviado.

O ciclo de vida da transação

Toda transação carrega um status normalizado que é idêntico entre os provedores. O diagrama abaixo mostra como uma transação transita entre os estados canônicos.

Roteamento e resiliência

Dois recursos transformam uma lista de provedores conectados em uma camada de pagamento resiliente: roteamento inteligente e fallback em cascata.

Roteamento inteligente

O roteamento inteligente escolhe qual provedor processa uma determinada transação. Você define regras no Dashboard, e o Tokeflow as avalia por transação usando atributos como país, moeda, método de pagamento, bandeira do cartão e valor. O roteamento permite direcionar o tráfego para o provedor com a melhor economia ou as melhores taxas de aprovação para cada segmento do seu volume — sem alterar uma única linha de código de integração. Quando uma regra corresponde, seu identificador é registrado na transação, de modo que toda decisão é auditável.

Fallback em cascata

O fallback em cascata decide o que acontece em seguida quando um provedor não consegue concluir o pagamento. Se o provedor selecionado retornar uma recusa leve — uma falha passível de nova tentativa, como um timeout do emissor, um erro temporário de rede ou um "do not honor" transitório — o Tokeflow automaticamente repete a mesma autorização com o próximo provedor elegível na rota. Isso recupera receita que, de outra forma, seria perdida para falhas transitórias. Recusas rígidas (como um cartão inválido ou roubado) são terminais e nunca são repetidas, de modo que os clientes não são cobrados em um cartão que o emissor recusou.

O resultado é o mesmo objeto de transação normalizado, independentemente de quantos provedores foram tentados. Sua integração enxerga um único contrato; o Tokeflow cuida da orquestração por trás dele.

Próximos passos

• Autenticação — chaves, escopos e o envelope de requisição.
• Bridge SDK — colete cartões com segurança no navegador.
• Transações — criar, capturar, cancelar (void) e reembolsar.
• Webhooks — verifique assinaturas e reaja a eventos.