@conch-tech/web-component

v0.1.2

Published

7 months ago

Conch Payment Collection Web Component SDK

0High
0Medium
0Low

conch-admin

payment sdk react typescript conch

@conch-tech/web-component

A secure, embeddable JavaScript SDK for ConchPay payment processing. Built with TypeScript, React (modular component design), and comprehensive Jest + Testing Library test coverage.

Tech Stack

TypeScript - Full type safety and modern JavaScript features
React - Modular component design for flexible integration
Jest + Testing Library - Comprehensive unit and integration tests
Tailwind CSS - Modern, customizable styling
Framer Motion - Smooth animations and transitions

Features

1. 🔧 Embeddable Widget

Load via script tag or NPM installation
Render hosted/embedded/pop-up checkout experiences
Multiple integration modes: React component, modal, or iframe

2. 🎨 UI Customization Props

Theme color, font, and logo URL customization
Currency and language localization
Custom metadata fields
Responsive design for all devices

3. 💳 Payment Methods UI

Bank card form (PCI-compliant tokenization)
Crypto QR codes and wallet connect
Mobile money integration
Bank transfer options

4. 🔗 API Hooks

initializePayment() — starts payment session
onSuccess, onFailure, onClose event handlers
Real-time status updates and callbacks

5. 🔒 Security

Tokenize card details, never store in frontend
HMAC signatures for callback validation
Session-based authentication with public keys only
No sensitive data stored client-side

Installation

NPM Installation

npm install @conch-tech/web-component
# or
yarn add @conch-tech/web-component
# or
pnpm add @conch-tech/web-component

Script Tag Installation

<script src="https://unpkg.com/@conch-tech/web-component@latest/dist/index.js"></script>
<script>
  // Initialize Conch SDK
  const conch = new Conch('pk_test_your_public_key');
</script>

Quick Start

React Component Usage

import React from 'react';
import { CheckoutUI, initializePayment } from '@conch-tech/web-component';

function App() {
  const paymentConfig = {
    merchantId: 'your-merchant-id',
    apiKey: 'your-api-key',
    amount: 100,
    currency: 'USD',
    description: 'Product purchase',
    environment: 'sandbox', // or 'production'
  };

  const handleSuccess = (result) => {
    console.log('Payment successful:', result);
  };

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

  // Initialize payment session
  const startPayment = async () => {
    const session = await initializePayment(paymentConfig);
    if (session.success) {
      console.log('Session created:', session.data);
    }
  };

  return (
    <CheckoutUI
      config={paymentConfig}
      callbacks={{
        onSuccess: handleSuccess,
        onFailure: handleError,
      }}
    />
  );
}

Script Tag Usage

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@conch-tech/web-component@latest/dist/index.js"></script>
</head>
<body>
  <div id="conch-checkout"></div>
  
  <script>
    const conch = new Conch('pk_test_your_public_key');
    
    conch.initializePayment({
      merchantId: 'your-merchant-id',
      amount: 100,
      currency: 'USD',
      description: 'Product purchase'
    }).then(session => {
      if (session.success) {
        conch.renderCheckout('#conch-checkout', {
          onSuccess: (result) => console.log('Success:', result),
          onFailure: (error) => console.error('Error:', error),
          onClose: () => console.log('Checkout closed')
        });
      }
    });
  </script>
</body>
</html>

Customization

Basic Branding

const brandingConfig = {
  branding: {
    logoUrl: "https://example.com/logo.svg",
    primaryColor: "#4F46E5",
    fontFamily: "Inter, sans-serif",
    buttonStyle: "rounded", // "rounded" | "square" | "pill"
    theme: "light", // "light" | "dark" | "auto"
  },
};

<CheckoutUI
  config={paymentConfig}
  uiConfig={brandingConfig}
  callbacks={callbacks}
/>

Advanced Configuration

const advancedConfig = {
  branding: {
    logoUrl: "https://example.com/logo.svg",
    primaryColor: "#4F46E5",
    fontFamily: "Inter, sans-serif",
    buttonStyle: "rounded",
    theme: "light",
    brandName: "Your Company",
  },
  layout: {
    orientation: "vertical", // "horizontal" | "vertical"
    maxWidth: "400px",
    padding: "24px",
    borderRadius: "12px",
    showHeader: true,
    showFooter: true,
    centered: true,
  },
  content: {
    headerText: "Complete Your Payment",
    buttons: {
      pay: "Pay Now",
      cancel: "Cancel",
      back: "Back",
      next: "Continue",
      confirm: "Confirm Payment",
    },
    labels: {
      email: "Email Address",
      amount: "Amount",
      cardNumber: "Card Number",
      // ... more labels
    },
  },
  steps: {
    enabled: true,
    showIndicators: true,
    allowBack: true,
    steps: {
      amount: "Amount",
      method: "Payment Method",
      details: "Payment Details",
      confirmation: "Confirmation",
    },
  },
  animations: {
    enabled: true,
    duration: 300,
    easing: "easeInOut",
  },
  accessibility: {
    highContrast: false,
    reduceMotion: false,
    focusTrap: true,
  },
};

Modal Usage

function PaymentModal() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Open Checkout
      </button>
      
      <CheckoutUI
        config={paymentConfig}
        uiConfig={uiConfig}
        callbacks={callbacks}
        isModal={true}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  );
}

Payment Methods

<CheckoutUI
  config={paymentConfig}
  paymentMethods={['card', 'crypto', 'mobile_money']}
  defaultPaymentMethod="card"
  callbacks={callbacks}
/>

Event Callbacks

const callbacks = {
  onSuccess: (result) => {
    console.log('Payment completed:', result);
    // Handle successful payment
  },
  onFailure: (error) => {
    console.error('Payment failed:', error);
    // Handle payment failure
  },
  onClose: () => {
    console.log('Checkout closed');
    // Handle checkout close
  },
  onStatusChange: (status) => {
    console.log('Payment status:', status);
    // Handle status changes: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'
  },
};

Security Features

The Conch Web Component prioritizes security with multiple layers of protection:

🔐 Tokenization

Card details are tokenized immediately upon entry
No sensitive payment data is stored in the frontend
PCI-compliant handling of payment information

🔑 Session-Based Authentication

Uses public keys only in frontend code
Session tokens for secure API communication
Automatic session validation and expiration handling

✅ HMAC Signatures

All callback validations use HMAC signatures
Prevents tampering with payment results
Ensures data integrity throughout the payment flow

🛡️ Secure SDK Architecture

No private keys or secrets in client-side code
Secure payment data transmission
Built-in session management and cleanup

Basic Usage

import React from 'react';
import { ConchPayment, PaymentConfig } from '@conch-tech/web-component';

function App() {
  const config: PaymentConfig = {
    merchantId: 'your-merchant-id',
    apiKey: 'your-api-key',
    amount: 2000, // $20.00 in cents
    currency: 'USD',
    description: 'Test payment',
    environment: 'sandbox', // or 'production'
  };

  const handleSuccess = (result) => {
    console.log('Payment successful:', result);
  };

  const handleFailure = (error) => {
    console.error('Payment failed:', error);
  };

  return (
    <ConchPayment
      config={config}
      callbacks={{
        onSuccess: handleSuccess,
        onFailure: handleFailure,
      }}
    />
  );
}

Using the Secure SDK Class

import { SecureConchSDK } from '@conch-tech/web-component';

// Use public key for secure session-based authentication
const sdk = new SecureConchSDK('pk_test_your_public_key', 'sandbox');

// Create a secure payment session (no private keys in frontend)
const session = await sdk.createSecureSession({
  merchantId: 'your-merchant-id',
  amount: 2000,
  currency: 'USD',
  description: 'Test payment',
});

if (session.success) {
  console.log('Secure session created:', session.data);
  // Session token is automatically managed for security
}

Using React Hooks

import React from 'react';
import { usePayment, PaymentConfig } from '@conch-tech/web-component';

function PaymentComponent() {
  const {
    session,
    loading,
    error,
    startPayment,
    processPayment,
    resetPayment,
  } = usePayment({
    onSuccess: (result) => console.log('Success:', result),
    onFailure: (error) => console.error('Error:', error),
  });

  const config: PaymentConfig = {
    merchantId: 'your-merchant-id',
    apiKey: 'your-api-key',
    amount: 2000,
    currency: 'USD',
  };

  const handleStartPayment = () => {
    startPayment(config);
  };

  return (
    <div>
      {loading && <p>Loading...</p>}
      {error && <p>Error: {error}</p>}
      {session && <p>Session ID: {session.id}</p>}
      
      <button onClick={handleStartPayment} disabled={loading}>
        Start Payment
      </button>
      
      <button onClick={resetPayment}>
        Reset
      </button>
    </div>
  );
}

Components

ConchPayment

The main payment component for embedding payment functionality.

<ConchPayment
  config={paymentConfig}
  callbacks={paymentCallbacks}
  className="custom-payment-class"
/>

PaymentModal

A modal component for payment processing.

<PaymentModal
  config={paymentConfig}
  callbacks={paymentCallbacks}
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
/>

PaymentWidget

A compact widget component for payment display.

<PaymentWidget
  config={paymentConfig}
  callbacks={paymentCallbacks}
  style={{ width: '300px' }}
/>

Configuration

PaymentConfig

interface PaymentConfig {
  merchantId: string;           // Your merchant ID
  apiKey: string;              // Your API key
  amount: number;              // Amount in cents
  currency: string;            // Currency code (USD, EUR, etc.)
  description?: string;        // Payment description
  metadata?: Record<string, any>; // Additional metadata
  theme?: ThemeConfig;         // UI customization
  paymentMethods?: PaymentMethod[]; // Allowed payment methods
  environment?: 'sandbox' | 'production'; // Environment
}

ThemeConfig

interface ThemeConfig {
  primaryColor?: string;       // Primary color
  backgroundColor?: string;    // Background color
  textColor?: string;         // Text color
  borderRadius?: string;      // Border radius
  fontFamily?: string;        // Font family
  logoUrl?: string;           // Logo URL
}

PaymentCallbacks

interface PaymentCallbacks {
  onSuccess?: (result: PaymentResult) => void;
  onFailure?: (error: PaymentResult) => void;
  onClose?: () => void;
  onStatusChange?: (status: PaymentSession['status']) => void;
}

Utilities

The SDK includes various utility functions for validation and formatting:

Validation

import {
  isValidEmail,
  isValidCardNumber,
  isValidCVV,
  isValidExpiry,
  isValidAmount,
  isValidCryptoAddress,
} from '@conch-tech/web-component';

// Validate email
const emailValid = isValidEmail('[email protected]');

// Validate card number
const cardValid = isValidCardNumber('4111111111111111');

// Validate amount
const amountValid = isValidAmount(2000, 'USD');

Formatting

import {
  formatAmount,
  formatCardNumber,
  formatExpiry,
  formatCryptoAmount,
} from '@conch-tech/web-component';

// Format amount
const formatted = formatAmount(2000, 'USD'); // "$20.00"

// Format card number
const cardFormatted = formatCardNumber('4111111111111111'); // "4111 1111 1111 1111"

// Format expiry
const expiryFormatted = formatExpiry('1225'); // "12/25"

API Reference

SecureConchSDK

class SecureConchSDK {
  constructor(publicKey: string, environment?: 'sandbox' | 'production');
  
  // Create secure session without exposing private keys
  createSecureSession(config: SessionPaymentConfig): Promise<ApiResponse<PaymentSession>>;
  
  // Get session status with optional session token
  getSessionStatus(sessionId: string, sessionToken?: string): Promise<ApiResponse<PaymentSession>>;
  
  // Confirm payment with tokenized data
  confirmSecurePayment(sessionId: string, securePaymentData: SecurePaymentData): Promise<ApiResponse<any>>;
  
  // Validate current session
  validateCurrentSession(): SessionValidationResult;
  
  // Clear session data
  clearSession(): void;
  
  // Get current session
  getCurrentSession(): PaymentSession | null;
}

initializePayment Function

// Initialize payment session
function initializePayment(config: PaymentConfig): Promise<ApiResponse<PaymentInitResponse>>;

usePayment Hook

const {
  session,        // Current payment session
  loading,        // Loading state
  error,          // Error message
  isProcessing,   // Processing state
  startPayment,   // Start payment function
  resetPayment,   // Reset payment function
  processPayment, // Process payment function
} = usePayment(callbacks?);

Error Handling

The SDK provides comprehensive error handling with secure session management:

try {
  const result = await sdk.createSecureSession(config);
  
  if (!result.success) {
    console.error('Session creation failed:', result.error);
    return;
  }
  
  // Handle success - session token is automatically managed
  console.log('Secure session created:', result.data);
  
  // Validate session before proceeding
  const validation = sdk.validateCurrentSession();
  if (!validation.isValid) {
    console.error('Session validation failed:', validation.error);
    return;
  }
  
} catch (error) {
  console.error('Unexpected error:', error);
  // Clear any invalid session data
  sdk.clearSession();
}

TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

import type {
  // Core payment types
  PaymentConfig,
  SessionPaymentConfig,
  PaymentSession,
  PaymentResult,
  PaymentCallbacks,
  
  // Security types
  SecurePaymentData,
  SessionValidationResult,
  
  // UI and branding types
  ThemeConfig,
  BrandingConfig,
  CheckoutUIConfig,
  
  // API types
  ApiResponse,
  PaymentInitResponse,
  PaymentMethod,
  
  // Hook types
  UsePaymentReturn,
  UsePaymentState,
  UsePaymentActions,
} from '@conch-tech/web-component';

Testing

The SDK includes comprehensive test utilities:

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Development

# Install dependencies
pnpm install

# Start development mode
npm run dev

# Build the package
npm run build

# Lint code
npm run lint

# Type check
npm run type-check

Browser Support

Chrome 70+
Firefox 65+
Safari 12+
Edge 79+

License

MIT License - see LICENSE file for details.

Support

For support and questions:

Documentation: https://docs.useconch.com
Email: [email protected]
GitHub Issues: https://github.com/conch/web-sdk/issues

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@conch-tech/web-component

Tech Stack

Features

1. 🔧 Embeddable Widget

2. 🎨 UI Customization Props

3. 💳 Payment Methods UI

4. 🔗 API Hooks

5. 🔒 Security

Installation

NPM Installation

Script Tag Installation

Quick Start

React Component Usage

Script Tag Usage

Customization

Basic Branding

Advanced Configuration

Modal Usage

Payment Methods

Event Callbacks

Security Features

🔐 Tokenization

🔑 Session-Based Authentication

✅ HMAC Signatures

🛡️ Secure SDK Architecture

Basic Usage

Using the Secure SDK Class

Using React Hooks

Components

ConchPayment

PaymentModal

PaymentWidget

Configuration

PaymentConfig

ThemeConfig

PaymentCallbacks

Utilities

Validation

Formatting

API Reference

SecureConchSDK

initializePayment Function

usePayment Hook

Error Handling

TypeScript Support

Testing

Development

Browser Support

License

Support