React integration

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

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

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

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

export default function App() {
  return (
    <TokeflowProvider
      config={{
        publicKey: 'pk_test_your_public_key',
        locale: 'pt-BR',
        onError: (error) => console.error(error.code, error.message),
      }}
    >
      <YourApp />
    </TokeflowProvider>
  );
}

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

function PaymentForm() {
  const { tokeflow, session, isReady, error } = useTokeflow();

  if (error) return <div role="alert">Error: {error.message}</div>;
  if (!isReady) return <div>Loading payment form…</div>;

  // `tokeflow` is the initialized bridge instance.
  return <p>Session {session?.id} is ready.</p>;
}

import { useCapabilities, useSessionSettings } from '@tokeflow_com/bridge-js/react';

function CardBrands() {
  const capabilities = useCapabilities();
  const settings = useSessionSettings();

  if (!settings) return null;

  return (
    <ul>
      {settings.allowedCardBrands?.map((brand) => (
        <li key={brand}>{brand}</li>
      ))}
    </ul>
  );
}

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

function MethodPicker() {
  const methods = useAvailablePaymentMethods(); // ('cards' | 'pix' | 'applePay' | 'googlePay')[]

  return (
    <div>
      {methods.includes('cards') && <CardForm />}
      {methods.includes('pix') && <PixForm />}
      {methods.includes('applePay') && <ApplePayButton />}
    </div>
  );
}

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

function CheckoutSummary() {
  const { context, isLoading, error, refresh } = useCheckout();

  if (error) return <p role="alert">{error.message}</p>;
  if (isLoading || !context) return <p>Loading…</p>;

  return (
    <>
      <ul>
        {context.checkout.items.map((item) => (
          <li key={item.id}>
            {item.offerId} — {item.amount} {context.checkout.selectedCurrency}
          </li>
        ))}
      </ul>
      <button onClick={refresh}>Refresh</button>
    </>
  );
}

import { useRef } from 'react';
import { CardElement, CardElementRef } from '@tokeflow_com/bridge-js/react';

function CombinedCardForm() {
  const cardRef = useRef<CardElementRef>(null);

  return (
    <CardElement
      ref={cardRef}
      id="card"
      onReady={() => console.log('Ready')}
      onChange={(e) => console.log('Complete:', e.complete, 'Error:', e.error?.message)}
      className="my-card-element"
    />
  );
}

// Later, on submit:
//   await tokeflow.cards.tokenize({ card: cardRef.current.element });

import { useRef } from 'react';
import {
  CardNumberElement,
  CardExpirationElement,
  CardCvcElement,
  CardNumberElementRef,
  CardExpirationElementRef,
  CardCvcElementRef,
} from '@tokeflow_com/bridge-js/react';

function SplitCardForm() {
  const numberRef = useRef<CardNumberElementRef>(null);
  const expiryRef = useRef<CardExpirationElementRef>(null);
  const cvcRef = useRef<CardCvcElementRef>(null);

  // On submit, pass the underlying instances — note the key is `expiration`:
  //   await tokeflow.cards.tokenize({
  //     cardNumber: numberRef.current.element,
  //     expiration: expiryRef.current.element,
  //     cvc: cvcRef.current.element,
  //   });

  return (
    <>
      <CardNumberElement ref={numberRef} id="number" />
      <CardExpirationElement ref={expiryRef} id="expiry" />
      <CardCvcElement ref={cvcRef} id="cvc" />
    </>
  );
}

const token = await tokeflow.cards.tokenize({
  card: cardRef.current.element,
});
// token.tokenId -> 'tok_…'

interface CardToken {
  tokenId: string;       // your Tokeflow token reference (tok_…)
  type: 'card';
  brand: string;         // 'visa', 'mastercard', etc.
  last4: string;         // last 4 digits
  expiryMonth: string;   // e.g. '12'
  expiryYear: string;    // e.g. '2029'
  bin?: string;          // bank identification number (optional)
  createdAt?: string;    // ISO 8601 timestamp (optional)
}

const token = await tokeflow.cards.tokenize(
  { card: cardRef.current.element },
  { metadata: { cartId: 'cart_123' } }
);

import React, { useRef, useState, FormEvent } from 'react';
import {
  TokeflowProvider,
  useTokeflow,
  CardElement,
  CardElementRef,
} from '@tokeflow_com/bridge-js/react';
import { TokeflowError } from '@tokeflow_com/bridge-js';

function PaymentForm() {
  const { tokeflow, isReady } = useTokeflow();
  const cardRef = useRef<CardElementRef>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
    if (!tokeflow || !cardRef.current?.element) return;

    setLoading(true);
    setError(null);

    try {
      // 1. Tokenize in the browser — raw card data never reaches your servers.
      const token = await tokeflow.cards.tokenize({
        card: cardRef.current.element,
      });

      // 2. Send ONLY the token reference to your backend.
      const res = await fetch('/api/payments', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ tokenId: token.tokenId }),
      });

      if (!res.ok) throw new Error('Payment could not be completed.');

      alert('Payment successful!');
    } catch (err) {
      if (err instanceof TokeflowError) {
        // Field-level error from the secure element / tokenization.
        setError(err.message);
      } else {
        setError(err instanceof Error ? err.message : 'Unexpected error.');
      }
    } finally {
      setLoading(false);
    }
  };

  if (!isReady) return <div>Loading payment form…</div>;

  return (
    <form onSubmit={handleSubmit}>
      <div className="form-group">
        <label htmlFor="card-element">Card details</label>
        <CardElement
          ref={cardRef}
          id="card-element"
          onChange={(e) => setError(e.error?.message ?? null)}
        />
      </div>

      {error && (
        <div className="error" role="alert">
          {error}
        </div>
      )}

      <button type="submit" disabled={loading}>
        {loading ? 'Processing…' : 'Pay now'}
      </button>
    </form>
  );
}

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

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1d9c2e-7a3b-4c8e-9f21-0a1b2c3d4e5f" \
  -d '{
    "amount": 9900,
    "currency": "BRL",
    "payment_method": "credit_card",
    "card_ciphertext_id": "tok_8f3c2a1b"
  }'

{
  "success": true,
  "data": {
    "id": "tx_7c9a1f2b",
    "status": "authorized",
    "amount": 9900,
    "currency": "BRL",
    "payment_method": "credit_card",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

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

try {
  const token = await tokeflow.cards.tokenize({ card: cardRef.current.element });
} catch (err) {
  if (err instanceof TokeflowError) {
    switch (err.code) {
      case TokeflowErrorCode.INVALID_CARD:
        setError('Please check your card number.');
        break;
      case TokeflowErrorCode.EXPIRED_CARD:
        setError('This card has expired.');
        break;
      case TokeflowErrorCode.ELEMENT_INCOMPLETE:
        setError('Please complete all card fields.');
        break;
      case TokeflowErrorCode.UNSUPPORTED_CARD_BRAND:
        setError('This card brand is not supported.');
        break;
      case TokeflowErrorCode.NETWORK_ERROR:
        setError('Network error. Please try again.');
        break;
      default:
        setError(err.message);
    }
    console.log('code:', err.code, 'requestId:', err.requestId);
  }
}

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

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