SDK API reference

The TokeflowBridge class, configuration options, modules, element factories, and exported TypeScript types for the Bridge SDK.

This page is the surface-level reference for @tokeflow_com/bridge-js. For task-oriented guides, see Quickstart, Elements, Tokenization, and Payment methods.

The SDK ships full TypeScript definitions — every type below is importable.

`TokeflowBridge`

The main entry point. Create one instance per checkout, call init(), create elements, then tokenize.

class TokeflowBridge {
  constructor(config: TokeflowBridgeConfig);

  init(): Promise<void>;   // creates a session and loads the secure elements runtime
  destroy(): void;         // tears down the bridge and releases all resources

  // Session & capabilities (synchronous getters; valid after init())
  getSession(): Session | null;
  getCapabilities(): Capabilities | null;
  getSessionSettings(): SessionSettings | null;
  getAvailablePaymentMethods(): AvailablePaymentMethod[];

  // Element factories
  createCardElement(options?: CardElementOptions): TokeflowCardElement;
  createCardNumberElement(options?): TokeflowCardNumberElement;
  createCardExpirationElement(options?): TokeflowCardExpirationElement;
  createCardCvcElement(options?): TokeflowCardCvcElement;
  createCardholderNameElement(options?): TokeflowCardholderNameElement;
  createTextElement(options?): TokeflowTextElement;
  createCpfElement(options?): TokeflowCpfElement;
  createAddressLine1Element(options?): TokeflowAddressLine1Element;
  createAddressLine2Element(options?): TokeflowAddressLine2Element;
  createCityElement(options?): TokeflowCityElement;
  createStateElement(options?): TokeflowStateElement;
  createPostalCodeElement(options?): TokeflowPostalCodeElement;
  createCountryElement(options?): TokeflowCountryElement;
  createApplePayButton(options?): TokeflowApplePayButton;
  createGooglePayButton(options?): TokeflowGooglePayButton;

  // Modules
  cards: Cards;
  pix: Pix;
  applePay: ApplePay;
  googlePay: GooglePay;
  checkout: Checkout;
  sessionManager: SessionManager;
}

Lifecycle

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

const tokeflow = new TokeflowBridge({ publicKey: 'pk_live_mer_xxxxxxxx' });

await tokeflow.init();                       // 1. initialize
const card = tokeflow.createCardElement();    // 2. create
card.mount('#card-element');                  // 3. mount
const token = await tokeflow.cards.tokenize({ card }); // 4. tokenize
// 5. send token.tokenId to your backend to charge
tokeflow.destroy();                           // 6. clean up when done

`TokeflowBridgeConfig`

Option	Type	Required	Default	Description
`publicKey`	`string`	Yes	—	Your Tokeflow public key (`pk_test_` or `pk_live_`). Safe to expose in the browser.
`environment`	`'sandbox' \| 'production'`	No	Auto	Auto-detected from the key (`pk_test_` → `sandbox`, `pk_live_` → `production`).
`brandName`	`string`	No	—	Merchant brand name shown in some hosted UI surfaces.
`checkoutSessionId`	`string`	No	—	Link the bridge to a backend-created checkout session.
`locale`	`TokeflowLocale`	No	`'en'`	Default locale for all elements. See Localization.
`translations`	`Partial<TokeflowTranslations>`	No	—	Override built-in translation strings.
`elementOptions`	`{ style?: ElementStyle; fonts?: string[] }`	No	—	Default styling/fonts applied to every element.
`sessionTTL`	`number`	No	Server-driven	Requested session lifetime in seconds.
`autoRefreshSession`	`boolean`	No	`true`	Refresh the session automatically before it expires.
`timeout`	`number`	No	`30000`	Request timeout in milliseconds.
`telemetry`	`boolean \| TelemetryOptions`	No	`true`	Anonymous error telemetry. Set `false` to disable; also disabled automatically when the browser sends Do-Not-Track.
`onSessionCreated`	`(session: Session) => void`	No	—	Called when a session is created.
`onSessionExpired`	`() => void`	No	—	Called when the session expires.
`onError`	`(error: TokeflowError) => void`	No	—	Global error handler.

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_live_mer_xxxxxxxx',
  locale: 'pt-BR',
  timeout: 15000,
  onError: (error) => console.error(error.code, error.message),
  onSessionCreated: (session) => console.log('Session:', session.id),
});

Telemetry is anonymous and scrubbed. When enabled, the SDK reports its own internal errors to help Tokeflow improve reliability. A fail-closed scrubber redacts any payment-relevant identifiers (card number, expiry, CVC, cardholder name, email, CPF, billing address) before anything is sent, and it never touches an error-monitoring or analytics setup you run in your own app. Disable it entirely with telemetry: false.

interface TelemetryOptions {
  enabled?: boolean;
  sampleRate?: number;         // 0..1
  environment?: string;        // defaults from the key
  release?: string;            // defaults to the SDK version
}

Modules

Module	Accessor	Purpose
`Cards`	`tokeflow.cards`	Tokenize card data. See Tokenization.
`Pix`	`tokeflow.pix`	Tokenize PIX details (Brazil).
`ApplePay`	`tokeflow.applePay`	Apple Pay configuration, support checks, and tokenization.
`GooglePay`	`tokeflow.googlePay`	Google Pay configuration, readiness checks, and tokenization.
`Checkout`	`tokeflow.checkout`	Read the linked checkout context. See Checkout context.
`SessionManager`	`tokeflow.sessionManager`	Inspect and refresh the underlying session.

Cards module

class Cards {
  tokenize(
    input:
      | TokeflowCardElement
      | { card: TokeflowCardElement; cardholderName?: TokeflowCardholderNameElement | string; billingAddress?: BillingAddressInput }
      | { cardNumber: TokeflowCardNumberElement; expiration: TokeflowCardExpirationElement; cvc: TokeflowCardCvcElement; cardholderName?: TokeflowCardholderNameElement | string; billingAddress?: BillingAddressInput },
    options?: TokenizeOptions
  ): Promise<CardToken>;
}

Element interface (all elements)

interface TokeflowElement<TOptions = unknown> {
  mount(target: string | HTMLElement): void;
  unmount(): void;
  update(options: TOptions): void;
  focus(): void;
  blur(): void;
  clear(): void;
  setValue(value: string): void;       // text-style elements only
  getState(): ElementState;
  on(event: ElementEvent, handler: EventHandler): void;
  off(event: ElementEvent, handler?: EventHandler): void;
}

See Elements for the full catalog, options, and events.

Exported types

import {
  TokeflowBridge,
  TokeflowError,
  TokeflowErrorCode,
  TokeflowCardElement,
} from '@tokeflow_com/bridge-js';

import type {
  TokeflowBridgeConfig,
  Session,
  CardToken,
  PixToken,
  TokenizeOptions,
  ElementStyle,
  ElementState,
  ElementChangeEvent,
  CardElementOptions,
  CheckoutContext,
  TelemetryOptions,
} from '@tokeflow_com/bridge-js';

// React types
import type {
  CardElementRef,
  CardNumberElementRef,
  CardExpirationElementRef,
  CardCvcElementRef,
} from '@tokeflow_com/bridge-js/react';

Browser support

The SDK targets the current versions of Chrome, Firefox, Safari, and Edge.

Error handling — TokeflowError and the full error-code table
React integration — provider, hooks, and components
Tokenization — cards.tokenize() input/output

SDK API reference

On this page