Tokeflow Bridge SDK

Secure payment tokenization SDK for the browser. Collect card details using PCI-compliant secure elements powered by Evervault.

The card data never touches your servers or ours — only secure token references are returned.

Features

• PCI-compliant - Secure iframes isolate card data
• Card Elements - Pre-built, customizable card inputs
• React Components - First-class React support with hooks
• Fully Customizable - Style elements to match your brand
• Lightweight - ~33KB minified
• TypeScript - Full type definitions included

Installation

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

CDN

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

Quick Start

Vanilla JavaScript

<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_test_your_key',
  });

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

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

      // Send token.tokenId to your server
      console.log('Token:', token.tokenId);
    });
  }

  init();
</script>

React

import { TokeflowProvider, CardElement, useTokeflow } from '@tokeflow/bridge-js/react';
import { useRef } from 'react';

function PaymentForm() {
  const { tokeflow, isReady } = useTokeflow();
  const cardRef = useRef(null);

  const handleSubmit = async (e) => {
    e.preventDefault();

    const token = await tokeflow.cards.tokenize({
      card: cardRef.current.element
    });

    console.log('Token:', token.tokenId);
  };

  if (!isReady) return <div>Loading...</div>;

  return (
    <form onSubmit={handleSubmit}>
      <CardElement ref={cardRef} id="card" />
      <button type="submit">Pay</button>
    </form>
  );
}

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

Card Elements

Create secure, isolated inputs for card data. Tokeflow supports two layouts:

Combined card element

A single iframe collecting number, expiry, and CVC together.

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

cardElement.on('change', (event) => {
  console.log('Valid:', event.valid, 'Complete:', event.complete);
});

Split card fields

Three independent iframes — one each for Card Number, Expiration, and CVC. Each field is isolated in its own cross-origin iframe, so a compromised page script cannot read or rewrite values across them. This layout matches the visual standard consumers see on most Brazilian and global checkouts.

const cardNumber = tokeflow.createCardNumberElement();
const expiration = tokeflow.createCardExpirationElement();
const cvc       = tokeflow.createCardCvcElement();

cardNumber.mount('#card-number');
expiration.mount('#card-expiry');
cvc.mount('#card-cvc');

const token = await tokeflow.cards.tokenize({
  cardNumber,
  expiration,
  cvc,
  cardholderName: 'João Silva',
});

Brand, BIN, and last4 are detected from the Card Number field's change event:

cardNumber.on('change', (event) => {
  console.log(event.brand, event.lastFour, event.bin);
});

Additional elements

const cardholderName = tokeflow.createCardholderNameElement();
const addressLine1   = tokeflow.createAddressLine1Element();
const city           = tokeflow.createCityElement();
const postalCode     = tokeflow.createPostalCodeElement();

Localization

Translate iframe labels, placeholders, and error messages without writing your own strings — the SDK ships with built-in en and pt-BR translation packs that match the Evervault translations schema.

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_test_xxx',
  locale: 'pt-BR', // applies to every element by default
});

// Override per element if needed:
const cardNumber = tokeflow.createCardNumberElement({
  locale: 'pt-BR',
  translations: {
    number: {
      label: 'Número do cartão',
      errors: { invalid: 'Verifique o número do cartão' },
    },
  },
});

Per-element translations win over SDK-init translations, which win over the built-in pack. Any field you don't override falls through to the built-in strings.

Tokenization

// Basic tokenization
const token = await tokeflow.cards.tokenize({ card: cardElement });

// With cardholder name
const token = await tokeflow.cards.tokenize({
  card: cardElement,
  cardholderName: 'John Doe'  // or pass element
});

// With billing address
const token = await tokeflow.cards.tokenize({
  card: cardElement,
  cardholderName: cardholderName,  // element
  billingAddress: {
    line1: addressLine1,  // element or string
    city: city,           // element or string
    postalCode: postalCode,  // element or string
    country: 'US'
  }
});

// Response
// {
//   tokenId: 'tok_xxx',
//   type: 'card',
//   brand: 'visa',
//   last4: '4242',
//   expiryMonth: '12',
//   expiryYear: '2029',
//   bin: '424242',
//   createdAt: '2024-01-01T00:00:00Z'
// }

Custom Metadata

const token = await tokeflow.cards.tokenize(
  { card: cardElement },
  { metadata: { orderId: 'order_123' } }
);

Styling

Customize the appearance of card elements to match your brand. Two style APIs are available:

// Tokeflow ElementStyle (mapped to Evervault's theme under the hood)
const cardElement = tokeflow.createCardElement({
  style: {
    base: {
      fontSize: '16px',
      fontWeight: 500,
      color: '#333',
      padding: '12px',
      ':focus': { color: '#0066ff' },
      '::placeholder': { color: '#999' },
    },
    invalid: { color: '#dc3545' },
    complete: { color: '#28a745' },
  },
  placeholder: {
    cardNumber: 'Card number',
    cardExpirationDate: 'MM/YY',
    cardSecurityCode: 'CVC',
  },
});

// Or pass a raw Evervault theme object as an escape hatch — for full control,
// or to use one of Evervault's built-in themes.
const cardElement2 = tokeflow.createCardElement({
  theme: {
    styles: {
      '.field input': { fontSize: 16, color: '#333' },
    },
  },
});

// Style text elements
const nameElement = tokeflow.createCardholderNameElement({
  placeholder: 'Cardholder Name',
  style: {
    base: {
      fontSize: '16px',
      padding: '12px',
      color: '#333',
      fontFamily: 'Arial, sans-serif'
    }
  }
});

Error Handling

import { TokeflowError, TokeflowErrorCode } from '@tokeflow/bridge-js';

try {
  const token = await tokeflow.cards.tokenize({ card: cardElement });
} catch (error) {
  if (error instanceof TokeflowError) {
    switch (error.code) {
      case TokeflowErrorCode.INVALID_CARD:
        console.log('Invalid card number');
        break;
      case TokeflowErrorCode.EXPIRED_CARD:
        console.log('Card has expired');
        break;
      default:
        console.log(error.message);
    }
  }
}

Configuration

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_test_xxx',        // Required
  environment: 'sandbox',           // 'sandbox' or 'production'
  baseUrl: 'https://api.custom.com', // Custom API URL
  timeout: 30000,                   // Request timeout (ms)
  onError: (error) => {},           // Global error handler
  onSessionCreated: (session) => {},
  onSessionExpired: () => {},
});

await tokeflow.init();

Documentation

For complete documentation, see:

• Integration Guide - Full API reference and examples
• Examples - Working code examples

Test Cards

| Brand | Number | Expiry | CVC | |-------|--------|--------|-----| | Visa | 4242 4242 4242 4242 | Any future | Any 3 digits | | Mastercard | 5555 5555 5555 4444 | Any future | Any 3 digits |

Security

• ✅ Card data encrypted by Evervault before transmission
• ✅ PCI DSS compliant tokenization
• ✅ Card data never reaches your servers in plaintext
• ✅ End-to-end encryption for all sensitive data
• ✅ Public keys safe to expose in client code
• ⚠️ Never use secret keys (sk_*) in the browser

Additional Payment Methods

PIX (Brazil)

const cpfElement = tokeflow.createCpfElement();
const nameElement = tokeflow.createTextElement({ placeholder: 'Full Name' });

const token = await tokeflow.pix.tokenize({
  cpf: cpfElement,
  name: 'João Silva',  // or pass nameElement
  email: '[email protected]'  // optional
});

Apple Pay

// Configure Apple Pay
tokeflow.applePay.configure({
  merchantId: 'merchant.com.yourcompany',
  merchantName: 'Your Company',
  countryCode: 'US',
  currencyCode: 'USD'
});

// Create payment request
const request = {
  total: { label: 'Total', amount: '10.00' }
};

// Begin payment
tokeflow.applePay.beginPayment(request, {
  onAuthorized: async ({ payment }) => {
    const token = await tokeflow.applePay.tokenize(payment);
    // Send token to server
  }
});

Google Pay

// Configure Google Pay
tokeflow.googlePay.configure({
  merchantId: 'your-merchant-id',
  merchantName: 'Your Company'
});

// Check availability
const canPay = await tokeflow.googlePay.isReadyToPay();

// Create payment request and tokenize
const paymentData = await googlePayClient.loadPaymentData(request);
const token = await tokeflow.googlePay.tokenize(paymentData);

Browser Support

Chrome, Firefox, Safari, Edge (latest versions)

License

MIT © Tokeflow