@tucontrol/bit-sdk

A React-based payment widget SDK for Bit payment integration.

Installation

# Using npm
npm install @tucontrol/bit-sdk

# Using yarn
yarn add @tucontrol/bit-sdk

# Using pnpm
pnpm add @tucontrol/bit-sdk

Requirements

• React 18.0.0 or higher
• React DOM 18.0.0 or higher

Features

• Email verification flow
• OTP (One-Time Password) authentication
• Card management (list, add, select)
• Client information collection
• Fingerprint integration for fraud detection
• Multi-language support (Spanish and English)
• TypeScript support

Usage

Basic Example

import { PaymentWidget } from '@tucontrol/bit-sdk';

function App() {
  const handleSuccess = (token: string) => {
    console.log('Payment token received:', token);
    // Handle successful payment
  };

  const handleError = (error) => {
    console.error('Payment error:', error);
    // Handle payment error
  };

  return (
    <PaymentWidget
      publicKey="your-public-key"
      apiBaseUrl="https://api.yourdomain.com"
      locale="es"
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
}

With Pre-filled Email

<PaymentWidget
  publicKey="your-public-key"
  email="[email protected]"
  apiBaseUrl="https://api.yourdomain.com"
  locale="en"
  onSuccess={handleSuccess}
  onError={handleError}
/>

Fingerprint Component

The SDK also exports a standalone Fingerprint component for fraud detection:

import { Fingerprint } from '@tucontrol/bit-sdk';

function App() {
  const handleFingerprintReady = (sessionId: string) => {
    console.log('Fingerprint session ID:', sessionId);
  };

  return (
    <Fingerprint
      publicKey="your-public-key"
      onFingerprintReady={handleFingerprintReady}
      onError={(error) => console.error(error)}
    />
  );
}

Props

PaymentWidget

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | publicKey | string | Yes | - | Your Bit API public key | | apiBaseUrl | string | No | '' | Base URL for the Bit API | | email | string | No | - | Pre-fill user email (skips email step) | | locale | 'es' \| 'en' | No | 'es' | Widget language | | onSuccess | (token: string) => void | No | - | Callback when payment is successful | | onError | (error: PaymentWidgetError) => void | No | - | Callback when an error occurs | | onExit | () => void | No | - | Callback when user exits the widget |

Fingerprint

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | publicKey | string | Yes | - | Your Bit API public key | | apiBaseUrl | string | Yes | - | Base URL for the Bit API | | onFingerprintReady | (sessionId: string) => void | No | - | Callback when fingerprint session is ready | | onError | (error: Error) => void | No | - | Callback when an error occurs |

Styling

✨ Zero style conflicts guaranteed! No CSS imports needed!

The widget uses CSS Modules with unique hash-based class names that are automatically injected when you use the component. No manual CSS imports required!

The styles are:

• ✅ CSS Modules with unique hashed class names (e.g., .styles-module__button___abc123)
• ✅ Auto-injected - No need to import CSS files manually
• ✅ Self-contained and completely isolated
• ✅ No external dependencies (Tailwind not needed)
• ✅ ~8KB included in the bundle
• ✅ 100% conflict-free - guaranteed no clashes with your app's styles
• ✅ Works out of the box - zero configuration

API Integration

The widget expects the following API endpoints:

• POST /otp - Send verification code
• POST /login - Verify code and login
• GET /cards - Get user's cards
• POST /card - Add a new card
• GET /card/:id - Get card token
• POST /fingerprint - Create fingerprint session

Development

Install Dependencies

yarn install

Build

yarn build

Development Mode

yarn dev

Type Check

yarn type-check

Lint

yarn lint

TypeScript

This package includes TypeScript definitions. All types are exported from the main entry point:

import type {
  PaymentCard,
  PaymentWidgetConfig,
  PaymentWidgetError,
  NewCardData,
  ApiResponse
} from '@tucontrol/bit-sdk';

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Tu-Control

Support

For issues or questions, please open an issue on GitHub.