tokeflow.com
DocumentaciónReferencia de APIDashboardsSDKsRegistro de cambios

Referencia de la API del SDK

La clase TokeflowBridge, las opciones de configuración, los módulos, las fábricas de elementos y los tipos de TypeScript exportados del Bridge SDK.

Esta página es la referencia a nivel de superficie de @tokeflow_com/bridge-js. Para guías orientadas a tareas, consulta Quickstart, Elements, Tokenization y Payment methods.

El SDK incluye definiciones completas de TypeScript — cada tipo de los que se muestran a continuación es importable.

TokeflowBridge

El punto de entrada principal. Crea una instancia por cada checkout, llama a init(), crea los elementos y luego tokeniza.

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;
  boleto: Boleto;
  applePay: ApplePay;
  googlePay: GooglePay;
  checkout: Checkout;
  sessionManager: SessionManager;
}

Ciclo de vida

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

OpciónTypeRequeridoPredeterminadoDescripción
publicKeystringSí—Tu clave pública de Tokeflow (pk_test_* o pk_live_*). Es seguro exponerla en el navegador.
environment'sandbox' | 'production'NoAutoSe detecta automáticamente a partir de la clave (pk_test_* → sandbox, pk_live_* → production).
brandNamestringNo—Nombre de la marca del Merchant que se muestra en algunas superficies de UI alojadas.
checkoutSessionIdstringNo—Vincula el bridge a una sesión de checkout creada en el backend.
localeTokeflowLocaleNo'en'Configuración regional predeterminada para todos los elementos. Consulta Localization.
translationsPartial<TokeflowTranslations>No—Sobrescribe las cadenas de traducción integradas.
elementOptions{ style?: ElementStyle; fonts?: string[] }No—Estilos/fuentes predeterminados que se aplican a cada elemento.
sessionTTLnumberNoDefinido por el servidorDuración de sesión solicitada, en segundos.
autoRefreshSessionbooleanNotrueRenueva la sesión automáticamente antes de que expire.
timeoutnumberNo30000Tiempo de espera de la solicitud en milisegundos.
telemetryboolean | TelemetryOptionsNotrueTelemetría anónima de errores. Establece false para desactivarla; también se desactiva automáticamente cuando el navegador envía Do-Not-Track.
onSessionCreated(session: Session) => voidNo—Se invoca cuando se crea una sesión.
onSessionExpired() => voidNo—Se invoca cuando la sesión expira.
onError(error: TokeflowError) => voidNo—Manejador global de errores.
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),
});

La telemetría es anónima y depurada. Cuando está habilitada, el SDK reporta sus propios errores internos para ayudar a Tokeflow a mejorar la fiabilidad. Un depurador de tipo fail-closed redacta cualquier identificador relevante para pagos (número de tarjeta, fecha de vencimiento, CVC, nombre del titular de la tarjeta, correo electrónico, CPF, dirección de facturación) antes de que se envíe cualquier cosa, y nunca toca una configuración de monitoreo de errores o de analítica que ejecutes en tu propia aplicación. Desactívala por completo con telemetry: false.

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

Módulos

MóduloAccesorPropósito
Cardstokeflow.cardsTokeniza datos de tarjeta. Consulta Tokenization.
Pixtokeflow.pixRegistra un pagador de PIX y obtén un token de pagador (Brasil). Consulta PIX.
Boletotokeflow.boletoRegistra un pagador de boleto y su dirección de facturación y obtén un token de pagador (Brasil, SDK 2.8.0+). Consulta Boleto.
ApplePaytokeflow.applePayConfiguración de Apple Pay, comprobaciones de compatibilidad y tokenización.
GooglePaytokeflow.googlePayConfiguración de Google Pay, comprobaciones de disponibilidad y tokenización.
Checkouttokeflow.checkoutLee el contexto de checkout vinculado. Consulta Checkout context.
SessionManagertokeflow.sessionManagerInspecciona y renueva la sesión subyacente.

Módulo Cards

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>;
}

Interfaz de elemento (todos los elementos)

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;
}

Consulta Elements para ver el catálogo completo, las opciones y los eventos.

Tipos exportados

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

import type {
  TokeflowBridgeConfig,
  Session,
  CardToken,
  PixToken,
  BoletoToken,
  PixTokenizeParams,
  BoletoTokenizeParams,
  PaymentInstructions,
  PixInstructions,
  BoletoInstructions,
  AvailablePaymentMethod,
  TokenizeOptions,
  TokenPurpose,
  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';

Compatibilidad con navegadores

El SDK está orientado a las versiones actuales de Chrome, Firefox, Safari y Edge.

Relacionado

Manejo de errores del SDK

Anterior

En esta página

TokeflowBridgeCiclo de vidaTokeflowBridgeConfigMódulosMódulo CardsInterfaz de elemento (todos los elementos)Tipos exportadosCompatibilidad con navegadoresRelacionado