Tokeflow Bridge SDK

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

Card data never touches your servers — 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/bridge-js
# or
yarn add @tokeflow/bridge-js
# or
bun add @tokeflow/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:

// Combined card element (number, expiry, CVC)
const cardElement = tokeflow.createCardElement();

// Mount to DOM
cardElement.mount('#card-element');

// Listen to events
cardElement.on('change', (event) => {
  console.log('Valid:', event.valid);
  console.log('Complete:', event.complete);
  console.log('Empty:', event.empty);
});

// Additional elements for billing information
const cardholderName = tokeflow.createCardholderNameElement();
const addressLine1 = tokeflow.createAddressLine1Element();
const city = tokeflow.createCityElement();
const postalCode = tokeflow.createPostalCodeElement();

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:

const cardElement = tokeflow.createCardElement({
  theme: {
    base: {
      fontSize: 16,
      fontWeight: 500,
      color: '#333',
      padding: '12px'
    }
  },
  placeholder: {
    cardNumber: 'Card number',
    cardExpirationDate: 'MM/YY',
    cardSecurityCode: 'CVC'
  }
});

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