Início rápido do SDK

Colete dados de cartão no navegador e obtenha uma referência de token em minutos com o Bridge SDK da Tokeflow — exemplos mínimos em Vanilla JS e React que você pode copiar e colar.

O Bridge SDK coleta os dados de pagamento no navegador sem expor seus servidores a dados brutos de cartão. Os campos seguros da Tokeflow rodam dentro de iframes isolados e cross-origin; os dados do cartão são criptografados no navegador e nunca chegam aos seus servidores. O SDK retorna uma referência de token que você envia ao seu backend para efetuar a cobrança.

Esta página leva você a um fluxo de tokenização funcional com dois exemplos mínimos e completos, de ponta a ponta — um em Vanilla JavaScript e outro em React. Para conhecer toda a superfície do SDK (elements, carteiras, contexto de checkout, tratamento de erros), consulte a visão geral do Bridge SDK.

Inicialize o SDK com uma chave pública (pk_…). As chaves públicas são restritas a escopos seguros para o cliente e podem ser enviadas com segurança no código do navegador. Nunca coloque uma chave secreta (sk_…) no navegador — consulte Autenticação.

Como funciona

O SDK cuida da coleta e da criptografia do cartão no navegador. Seu backend nunca vê o cartão — ele apenas recebe uma referência de token (tok_…) que usa para efetuar a cobrança.

A referência de token é de curta duração e de uso único. Sempre envie token.tokenId para o seu servidor; a cobrança em si acontece no lado do servidor com a sua chave secreta.

Instalação

Adicione o SDK a partir do seu gerenciador de pacotes ou carregue o build da CDN com uma tag de script.

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

O build da CDN expõe um objeto global Tokeflow (Tokeflow.TokeflowBridge, Tokeflow.TokeflowError, Tokeflow.TokeflowErrorCode):

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

Vanilla JavaScript

Uma página completa: um formulário com um card element, inicialização do SDK, mount e tokenização no submit. Ao enviar, o SDK retorna uma referência de token — envie token.tokenId ao seu servidor para efetuar a cobrança.

<!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 tokeflow = new Tokeflow.TokeflowBridge({
        publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx",
      });

      async function init() {
        // Creates a session and loads the secure elements runtime.
        await tokeflow.init();

        // Combined card element (number, expiry, CVC in one iframe).
        const cardElement = tokeflow.createCardElement();
        cardElement.mount("#card-element");

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

            const token = await tokeflow.cards.tokenize({ card: cardElement });
            console.log("Token:", token.tokenId); // tok_…

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

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

Está usando um bundler de módulos em vez da CDN? Importe a classe diretamente: import { TokeflowBridge } from "@tokeflow_com/bridge-js"; e use new TokeflowBridge({ publicKey }).

React

Envolva sua árvore com TokeflowProvider, renderize um CardElement e leia a instância do bridge com o hook useTokeflow. Passe a instância subjacente do element (por meio de .element da ref) para tokenize().

import { useRef, useState, FormEvent } from "react";
import {
  TokeflowProvider,
  useTokeflow,
  CardElement,
  CardElementRef,
} from "@tokeflow_com/bridge-js/react";

function PaymentForm() {
  const { tokeflow, isReady } = useTokeflow();
  const cardRef = useRef<CardElementRef>(null);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
    if (!tokeflow || !cardRef.current?.element) return;

    setLoading(true);
    try {
      const token = await tokeflow.cards.tokenize({
        card: cardRef.current.element,
      });
      console.log("Token:", token.tokenId); // tok_…

      // Send token.tokenId to YOUR server to create the charge.
      await fetch("/api/payments", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ tokenId: token.tokenId }),
      });
    } finally {
      setLoading(false);
    }
  };

  if (!isReady) return <div>Loading payment form…</div>;

  return (
    <form onSubmit={handleSubmit}>
      <CardElement ref={cardRef} id="card-element" />
      <button type="submit" disabled={loading}>
        {loading ? "Processing…" : "Pay"}
      </button>
    </form>
  );
}

export default function App() {
  return (
    <TokeflowProvider config={{ publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx" }}>
      <PaymentForm />
    </TokeflowProvider>
  );
}

O provider inicializa o bridge para você. Aguarde isReady antes de chamar tokenize() — até que a sessão seja criada e os campos seguros sejam montados, o bridge não está pronto para tokenizar.

A resposta do token

tokeflow.cards.tokenize(...) resolve para um CardToken. O único campo que você repassa adiante é tokenId (uma referência tok_…); o restante são metadados de exibição não sensíveis.

// {
//   tokenId: 'tok_a1b2c3d4e5',  // the reference you send to your server
//   type: 'card',
//   brand: 'visa',
//   last4: '4242',
//   expiryMonth: '12',
//   expiryYear: '2029',
//   bin: '424242',
//   createdAt: '2026-01-01T00:00:00.000Z'
// }

Field	Type	Descrição
`tokenId`	`string`	A referência do token da Tokeflow (`tok_…`). Envie isto ao seu servidor para efetuar a cobrança.
`type`	`string`	Sempre `card` para tokens de cartão.
`brand`	`string`	Bandeira do cartão, por exemplo `visa`, `mastercard`.
`last4`	`string`	Últimos quatro dígitos, para exibição.
`expiryMonth`	`string`	Mês de validade, por exemplo `12`.
`expiryYear`	`string`	Ano de validade, por exemplo `2029`.
`bin`	`string`	Número de identificação do banco (opcional).
`createdAt`	`string`	Timestamp ISO 8601 (opcional).

Cobre o token a partir do seu servidor

A referência de token não é uma cobrança — é um identificador (handle). Seu backend cria a transação com a sua chave secreta, referenciando o token por meio de card_ciphertext_id. Envie um Idempotency-Key para que uma nova tentativa nunca gere cobrança em duplicidade.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_2026_0623_attempt_1" \
  -d '{
    "customer_id": "cust_a1b2c3d4e5",
    "amount": 9900,
    "currency": "BRL",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "capture": true,
    "card_ciphertext_id": "tok_a1b2c3d4e5"
  }'

O fluxo completo de cobrança — sessões de checkout, captura, reembolsos e leitura da linha do tempo de tentativas — está em Transações. Para o caminho de ponta a ponta, das chaves ao webhook, consulte o Início rápido.

Nunca envie números brutos de cartão, CVCs ou datas de validade para o seu próprio backend. Somente a referência tok_… produzida pelo SDK deve sair do navegador.

Próximos passos

Visão geral do Bridge SDK — elements, carteiras, localização e o modelo completo de configuração.
Autenticação — chaves públicas vs. secretas e os cabeçalhos de autenticação do SDK.
Transações — cobre o token e depois capture, cancele (void) ou reembolse.
Início rápido — o passo a passo completo do zero ao pagamento.