Bridge SDK overview

The Bridge SDK (@tokeflow_com/bridge-js) is Tokeflow's client-side library for collecting sensitive payment data in the browser and turning it into a safe token reference. Your application never sees a raw card number — you receive a short-lived tok_… reference and send that to your backend to charge.

Tokeflow is the orchestration layer behind your platform. The Bridge SDK is the front door: it captures payment details inside isolated, cross-origin iframes, encrypts them in the browser, and hands your code a token. Your server then creates a transaction through the Tokeflow API, and your connected providers do the processing and settlement.

Why the Bridge SDK

Collecting card data directly on your own pages pulls your servers into PCI DSS scope and makes you responsible for protecting cardholder data. The Bridge SDK removes that burden.

• PCI-friendly by design — Card fields render inside isolated, cross-origin iframes. Card data is encrypted in the browser and never touches your servers or your page scripts.
• One tokenization flow, many payment methods — Cards, PIX, Apple Pay, and Google Pay all produce the same kind of token reference you forward to your backend.
• Checkout context — When your backend opens a checkout session, the SDK can read the priced items, selected currency, enabled payment methods, and the customer's saved instruments.
• Drop-in elements — Prebuilt, themeable input elements for card number, expiry, CVC, cardholder name, CPF, and billing address.
• Framework support — Works with vanilla JavaScript and ships first-class React bindings.
• Public-key auth — The SDK authenticates with a publishable key that is safe to ship in browser code. Your secret keys stay server-side.

How it fits together

The Bridge SDK runs in the browser and only ever holds token references. Your backend holds the secret key and performs the actual charge.

Installation

Install from your package manager of choice:

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 (script tag)

For pages without a build step, load the UMD build from a CDN. It exposes a global Tokeflow object.

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

The global exposes the main entry points:

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

The public key requirement

The Bridge SDK authenticates with a public key — never a secret key.

Public keys look like pk_live_org_… or pk_live_mer_…. They are restricted to client-safe scopes and are safe to embed in browser code. The SDK uses the key to create a short-lived session and to discover which payment methods your merchant has enabled. You issue and manage keys in the Tokeflow Dashboard during onboarding.

For the full anatomy of keys — secret vs public, environment, and organization vs merchant scope — see Environments and keys and Authentication.

Lifecycle

A typical integration follows five steps: construct the bridge, initialize it, create elements, tokenize, and send the token to your backend.

1. Construct the bridge

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

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

2. Initialize

init() creates a session and loads the secure elements runtime. It must resolve before you create or mount any element.

await bridge.init();

3. Create and mount elements

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

4. Tokenize

When the customer submits, tokenize the collected data. The card data is encrypted inside the iframe and exchanged for a token reference.

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

5. Send the token to your backend

Forward only the token reference. Your server uses its secret key to create the transaction.

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

Full vanilla example

<!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>

Payment methods

A single bridge instance covers every method your merchant has enabled. Discover them at runtime with bridge.getAvailablePaymentMethods(), which returns a subset of 'cards', 'pix', 'applePay', and 'googlePay'.

See Payment methods for the full API of each module.

Security

Security is the core reason to use the Bridge SDK rather than building your own card form.

• Card data is isolated from your page. Sensitive fields run inside isolated, cross-origin iframes. Your page scripts cannot read what the customer types.
• Card data is encrypted in the browser. It is encrypted before it leaves the page and never touches your servers — you only ever handle a token reference.
• PCI-friendly tokenization. Because raw card data never reaches your infrastructure, the SDK keeps cardholder data out of your PCI DSS scope.
• Public keys are safe in the browser. pk_… keys are restricted to client-safe scopes and are designed to be shipped in client code.
• Never use secret keys client-side. sk_… keys belong only on your server. Tokenization and session creation through the SDK require only a public key.

Next steps

• Quickstart — End-to-end payment in seven steps.
• React — Provider, hooks, and element components.
• Elements — Every input element, its options, events, and state.
• Tokenization — Tokenize input shapes, options, and the token response.
• Payment methods — Cards, PIX, Apple Pay, and Google Pay.