Visão geral do Bridge SDK

O Bridge SDK (@tokeflow_com/bridge-js) é a biblioteca client-side da Tokeflow para coletar dados de pagamento sensíveis no navegador e transformá-los em uma referência de token segura. Sua aplicação nunca vê um número de cartão bruto — você recebe uma referência tok_… de curta duração e a envia ao seu backend para efetuar a cobrança.

A Tokeflow é a camada de orquestração por trás da sua plataforma. O Bridge SDK é a porta de entrada: ele captura os detalhes de pagamento dentro de iframes isolados e cross-origin, criptografa-os no navegador e entrega ao seu código um token. Seu servidor então cria uma transação por meio da API da Tokeflow, e seus provedores conectados fazem o processamento e a liquidação.

Por que usar o Bridge SDK

Coletar dados de cartão diretamente nas suas próprias páginas coloca seus servidores no escopo do PCI DSS e o torna responsável por proteger os dados do portador do cartão. O Bridge SDK remove esse fardo.

• PCI-friendly por design — Os campos de cartão são renderizados dentro de iframes isolados e cross-origin. Os dados de cartão são criptografados no navegador e nunca tocam seus servidores nem os scripts da sua página.
• Um único fluxo de tokenização, muitos métodos de pagamento — Cartões, PIX, Apple Pay e Google Pay produzem todos o mesmo tipo de referência de token que você encaminha ao seu backend.
• Contexto de checkout — Quando seu backend abre uma sessão de checkout, o SDK pode ler os itens precificados, a moeda selecionada, os métodos de pagamento habilitados e os instrumentos salvos do cliente.
• Elementos drop-in — Elementos de input pré-construídos e personalizáveis para número do cartão, validade, CVC, nome do portador, CPF e endereço de cobrança.
• Suporte a frameworks — Funciona com JavaScript puro e traz bindings React de primeira classe.
• Autenticação por chave pública — O SDK autentica com uma chave publicável que é segura para ser enviada no código do navegador. Suas chaves secretas permanecem no servidor.

Como tudo se encaixa

O Bridge SDK roda no navegador e só mantém referências de token. Seu backend mantém a chave secreta e realiza a cobrança de fato.

Instalação

Instale a partir do gerenciador de pacotes de sua preferência:

npm install @tokeflow_com/bridge-js
# or
yarn add @tokeflow_com/bridge-js
# or
pnpm add @tokeflow_com/bridge-js
# or
bun add @tokeflow_com/bridge-js

CDN (tag script)

Para páginas sem etapa de build, carregue o build UMD a partir de um CDN. Ele expõe um objeto global Tokeflow.

<script src="https://unpkg.com/@tokeflow_com/bridge-js/dist/tokeflow.min.js"></script>

O global expõe os principais pontos de entrada:

Tokeflow.TokeflowBridge;   // the SDK class
Tokeflow.TokeflowError;    // error class
Tokeflow.TokeflowErrorCode; // error-code enum

O requisito da chave pública

O Bridge SDK autentica com uma chave pública — nunca uma chave secreta.

As chaves públicas têm o formato pk_live_org_… ou pk_live_mer_…. Elas são restritas a escopos seguros para o cliente e podem ser embutidas com segurança no código do navegador. O SDK usa a chave para criar uma sessão de curta duração e para descobrir quais métodos de pagamento seu Merchant tem habilitados. Você emite e gerencia as chaves no Dashboard da Tokeflow durante o onboarding.

Para a anatomia completa das chaves — secreta vs. pública, ambiente e escopo de Organization vs. Merchant — consulte Ambientes e chaves e Autenticação.

Ciclo de vida

Uma integração típica segue cinco passos: construir o bridge, inicializá-lo, criar elementos, tokenizar e enviar o token ao seu backend.

1. Construir o bridge

import { TokeflowBridge } from '@tokeflow_com/bridge-js';

const bridge = new TokeflowBridge({
  publicKey: 'pk_live_mer_your_public_key',
});

2. Inicializar

init() cria uma sessão e carrega o runtime de elementos seguros. Ele deve ser resolvido antes de você criar ou montar qualquer elemento.

await bridge.init();

3. Criar e montar elementos

const cardElement = bridge.createCardElement();
cardElement.mount('#card-element');

4. Tokenizar

Quando o cliente enviar, tokenize os dados coletados. Os dados de cartão são criptografados dentro do iframe e trocados por uma referência de token.

const token = await bridge.cards.tokenize({ card: cardElement });
console.log(token.tokenId); // 'tok_…'

5. Enviar o token ao seu backend

Encaminhe apenas a referência de token. Seu servidor usa sua chave secreta para criar a transação.

await fetch('/api/payments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tokenId: token.tokenId }),
});

Exemplo completo em JavaScript puro

<!DOCTYPE html>
<html>
  <head>
    <title>Payment Form</title>
  </head>
  <body>
    <form id="payment-form">
      <div id="card-element"></div>
      <button type="submit">Pay</button>
    </form>

    <script src="https://unpkg.com/@tokeflow_com/bridge-js/dist/tokeflow.min.js"></script>
    <script>
      const bridge = new Tokeflow.TokeflowBridge({
        publicKey: 'pk_live_mer_your_public_key',
      });

      async function init() {
        await bridge.init();

        const cardElement = bridge.createCardElement();
        cardElement.mount('#card-element');

        document
          .getElementById('payment-form')
          .addEventListener('submit', async (e) => {
            e.preventDefault();

            const token = await bridge.cards.tokenize({ card: cardElement });

            // Send token.tokenId to your server
            await fetch('/api/payments', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({ tokenId: token.tokenId }),
            });
          });
      }

      init();
    </script>
  </body>
</html>

Métodos de pagamento

Uma única instância do bridge cobre todos os métodos que seu Merchant tem habilitados. Descubra-os em tempo de execução com bridge.getAvailablePaymentMethods(), que retorna um subconjunto de 'cards', 'pix', 'applePay' e 'googlePay'.

Consulte Métodos de pagamento para a API completa de cada módulo.

Segurança

A segurança é a principal razão para usar o Bridge SDK em vez de construir seu próprio formulário de cartão.

• Os dados de cartão ficam isolados da sua página. Os campos sensíveis rodam dentro de iframes isolados e cross-origin. Os scripts da sua página não conseguem ler o que o cliente digita.
• Os dados de cartão são criptografados no navegador. Eles são criptografados antes de deixar a página e nunca tocam seus servidores — você só lida com uma referência de token.
• Tokenização PCI-friendly. Como os dados de cartão brutos nunca chegam à sua infraestrutura, o SDK mantém os dados do portador do cartão fora do seu escopo de PCI DSS.
• As chaves públicas são seguras no navegador. As chaves pk_… são restritas a escopos seguros para o cliente e foram projetadas para serem enviadas no código do cliente.
• Nunca use chaves secretas no lado do cliente. As chaves sk_… pertencem apenas ao seu servidor. A tokenização e a criação de sessão por meio do SDK exigem apenas uma chave pública.

Próximos passos

• Quickstart — Pagamento de ponta a ponta em sete passos.
• React — Provider, hooks e componentes de elementos.
• Elementos — Cada elemento de input, suas opções, eventos e estado.
• Tokenização — Formatos de input de tokenização, opções e a resposta do token.
• Métodos de pagamento — Cartões, PIX, Apple Pay e Google Pay.