@voxepay/checkout 0.3.2 → 0.3.4

package/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @voxepay/checkout - Modern Payment Checkout SDK
+ * 
+ * A beautiful, modern payment modal for the web by VoxePay.
+ * 
+ * @example
+ * ```html
+ * <script src="https://unpkg.com/@voxepay/checkout"></script>
+ * <script>
+ *   VoxePay.init({ apiKey: 'pk_live_xxxxx' });
+ *   
+ *   VoxePay.checkout({
+ *     amount: 4999,
+ *     currency: 'NGN',
+ *     onSuccess: (result) => console.log('Paid!', result),
+ *     onError: (error) => console.error('Failed', error),
+ *   });
+ * </script>
+ * ```
+ * 
+ * @packageDocumentation
+ */
+
+// Main SDK
+export { VoxePay, VoxePaySDK } from './voxepay';
+
+// Types
+export type {
+    VoxePayConfig,
+    VoxePayTheme,
+    CheckoutOptions,
+    PaymentResult,
+    PaymentError,
+    CardInfo,
+    BankTransferDetails,
+    PaymentMethod,
+} from './types';
+
+// Utilities (for advanced usage)
+export {
+    detectCardBrand,
+    validateCardNumber,
+    validateExpiry,
+    validateCVV,
+    luhnCheck,
+} from './utils/card-validator';
+
+export {
+    formatCardNumber,
+    formatExpiry,
+    formatCVV,
+    formatAmount,
+    getCurrencySymbol,
+} from './utils/formatter';
+
+export {
+    generateAuthData,
+    formatExpiryForApi,
+    cleanPan,
+} from './utils/encryption';
+
+export type { AuthDataParams } from './utils/encryption';
+
+export type {
+    InitiatePaymentRequest,
+    InitiatePaymentResponse,
+    ValidateOTPRequest,
+    ValidateOTPResponse,
+    ResendOTPRequest,
+} from './api/client';
+
+// Default export for convenience
+export { VoxePay as default } from './voxepay';

package/src/types.ts

@@ -0,0 +1,141 @@
+/**
+ * VoxePay Checkout Type Definitions
+ */
+
+/**
+ * Configuration for initializing VoxePay
+ */
+export interface VoxePayConfig {
+    /** Your VoxePay API key (e.g., vxp_live_xxxxx) */
+    apiKey: string;
+    /** Your VoxePay organization ID */
+    organizationId: string;
+    /** API base URL (defaults to https://devpay.voxepay.app) */
+    baseUrl?: string;
+    /** Theme mode: 'dark' (default), 'light', or 'auto' (follows system) */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Locale for formatting (e.g., 'en-US', 'en-NG') */
+    locale?: string;
+    /** Custom CSS variables to override default theme */
+    customStyles?: Partial<VoxePayTheme>;
+}
+
+/**
+ * Custom theme variables
+ */
+export interface VoxePayTheme {
+    '--voxepay-primary': string;
+    '--voxepay-secondary': string;
+    '--voxepay-accent': string;
+    '--voxepay-bg': string;
+    '--voxepay-surface': string;
+    '--voxepay-border': string;
+    '--voxepay-text': string;
+    '--voxepay-text-muted': string;
+    '--voxepay-border-radius': string;
+}
+
+/**
+ * Bank transfer account details shown to the user
+ */
+export interface BankTransferDetails {
+    /** Account number to transfer to */
+    accountNumber: string;
+    /** Name of the bank */
+    bankName: string;
+    /** Account holder name */
+    accountName: string;
+    /** Payment reference code (user should include in transfer) */
+    reference: string;
+    /** Expiry time in seconds (how long the account is valid for, e.g. 1800 = 30 minutes) */
+    expiresIn: number;
+}
+
+/** Supported payment method types */
+export type PaymentMethod = 'card' | 'bank_transfer';
+
+/**
+ * Options for opening a checkout session
+ */
+export interface CheckoutOptions {
+    /** Payment amount in smallest currency unit (e.g., kobo for NGN, cents for USD) */
+    amount: number;
+    /** ISO 4217 currency code (e.g., 'NGN', 'USD', 'EUR') */
+    currency: string;
+    /** Short description of the payment (shown in modal) */
+    description?: string;
+    /** Customer's email address (optional, for receipts) */
+    customerEmail?: string;
+    /** Customer's phone number */
+    customerPhone?: string;
+    /** Additional metadata to attach to the payment */
+    metadata?: Record<string, unknown>;
+    /** Payment methods to show. Defaults to ['card', 'bank_transfer'] */
+    paymentMethods?: PaymentMethod[];
+    /** Static bank transfer details (if known upfront) */
+    bankTransferDetails?: BankTransferDetails;
+    /** Callback to request bank transfer details dynamically (called when user selects bank transfer) */
+    onBankTransferRequested?: () => Promise<BankTransferDetails>;
+    /** @internal SDK config passed from VoxePaySDK to modal */
+    _sdkConfig?: {
+        apiKey: string;
+        organizationId: string;
+        baseUrl?: string;
+    };
+    /** Callback when payment succeeds */
+    onSuccess: (result: PaymentResult) => void;
+    /** Callback when payment fails */
+    onError: (error: PaymentError) => void;
+    /** Callback when modal is closed (optional) */
+    onClose?: () => void;
+}
+
+/**
+ * Result returned on successful payment
+ */
+export interface PaymentResult {
+    /** Unique payment ID */
+    id: string;
+    /** Payment status */
+    status: 'success' | 'pending';
+    /** Amount charged in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** ISO timestamp of the payment */
+    timestamp: string;
+    /** Transaction reference (if available) */
+    reference?: string;
+    /** Payment method used */
+    paymentMethod?: PaymentMethod;
+    /** Additional data from payment processor */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Error returned on payment failure
+ */
+export interface PaymentError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable?: boolean;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+
+/**
+ * Card information (sanitized - no full card numbers)
+ */
+export interface CardInfo {
+    /** Card brand (visa, mastercard, verve, etc.) */
+    brand: string;
+    /** Last 4 digits of the card */
+    last4: string;
+    /** Expiry month (1-12) */
+    expiryMonth: number;
+    /** Expiry year (full year) */
+    expiryYear: number;
+}

package/src/utils/card-validator.ts

@@ -0,0 +1,181 @@
+/**
+ * Card validation utilities for VoxePay Checkout
+ */
+
+export interface CardBrand {
+    name: string;
+    code: string;
+    pattern: RegExp;
+    lengths: number[];
+    cvvLength: number;
+}
+
+export const CARD_BRANDS: CardBrand[] = [
+    {
+        name: 'Visa',
+        code: 'visa',
+        pattern: /^4/,
+        lengths: [13, 16, 19],
+        cvvLength: 3,
+    },
+    {
+        name: 'Mastercard',
+        code: 'mastercard',
+        pattern: /^(5[1-5]|2[2-7])/,
+        lengths: [16],
+        cvvLength: 3,
+    },
+    {
+        name: 'Verve',
+        code: 'verve',
+        pattern: /^(506[0-9]|507[0-9]|6500)/,
+        lengths: [16, 18, 19],
+        cvvLength: 3,
+    },
+    {
+        name: 'American Express',
+        code: 'amex',
+        pattern: /^3[47]/,
+        lengths: [15],
+        cvvLength: 4,
+    },
+    {
+        name: 'Discover',
+        code: 'discover',
+        pattern: /^(6011|65|64[4-9])/,
+        lengths: [16, 19],
+        cvvLength: 3,
+    },
+];
+
+/**
+ * Detect card brand from card number
+ */
+export function detectCardBrand(cardNumber: string): CardBrand | null {
+    const cleaned = cardNumber.replace(/\s/g, '');
+    for (const brand of CARD_BRANDS) {
+        if (brand.pattern.test(cleaned)) {
+            return brand;
+        }
+    }
+    return null;
+}
+
+/**
+ * Luhn algorithm for card validation
+ */
+export function luhnCheck(cardNumber: string): boolean {
+    const cleaned = cardNumber.replace(/\s/g, '');
+    if (!/^\d+$/.test(cleaned)) return false;
+
+    let sum = 0;
+    let isEven = false;
+
+    for (let i = cleaned.length - 1; i >= 0; i--) {
+        let digit = parseInt(cleaned[i], 10);
+
+        if (isEven) {
+            digit *= 2;
+            if (digit > 9) {
+                digit -= 9;
+            }
+        }
+
+        sum += digit;
+        isEven = !isEven;
+    }
+
+    return sum % 10 === 0;
+}
+
+/**
+ * Validate card number
+ */
+export function validateCardNumber(cardNumber: string): { valid: boolean; error?: string } {
+    const cleaned = cardNumber.replace(/\s/g, '');
+
+    if (!cleaned) {
+        return { valid: false, error: 'Card number is required' };
+    }
+
+    if (!/^\d+$/.test(cleaned)) {
+        return { valid: false, error: 'Invalid card number' };
+    }
+
+    const brand = detectCardBrand(cleaned);
+
+    if (!brand) {
+        return { valid: false, error: 'Unsupported card type' };
+    }
+
+    if (!brand.lengths.includes(cleaned.length)) {
+        return { valid: false, error: 'Invalid card number length' };
+    }
+
+    if (!luhnCheck(cleaned)) {
+        return { valid: false, error: 'Invalid card number' };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Validate expiry date
+ */
+export function validateExpiry(expiry: string): { valid: boolean; error?: string } {
+    const cleaned = expiry.replace(/\s/g, '');
+
+    if (!cleaned) {
+        return { valid: false, error: 'Expiry date is required' };
+    }
+
+    const match = cleaned.match(/^(\d{2})\/(\d{2})$/);
+    if (!match) {
+        return { valid: false, error: 'Invalid format (MM/YY)' };
+    }
+
+    const month = parseInt(match[1], 10);
+    const year = parseInt(match[2], 10) + 2000;
+
+    if (month < 1 || month > 12) {
+        return { valid: false, error: 'Invalid month' };
+    }
+
+    const now = new Date();
+    const currentYear = now.getFullYear();
+    const currentMonth = now.getMonth() + 1;
+
+    if (year < currentYear || (year === currentYear && month < currentMonth)) {
+        return { valid: false, error: 'Card has expired' };
+    }
+
+    if (year > currentYear + 20) {
+        return { valid: false, error: 'Invalid expiry year' };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Validate CVV
+ */
+export function validateCVV(cvv: string, cardNumber?: string): { valid: boolean; error?: string } {
+    const cleaned = cvv.replace(/\s/g, '');
+
+    if (!cleaned) {
+        return { valid: false, error: 'CVV is required' };
+    }
+
+    if (!/^\d+$/.test(cleaned)) {
+        return { valid: false, error: 'Invalid CVV' };
+    }
+
+    const brand = cardNumber ? detectCardBrand(cardNumber) : null;
+    const expectedLength = brand?.cvvLength || 3;
+
+    if (cleaned.length !== expectedLength && cleaned.length !== 3 && cleaned.length !== 4) {
+        return { valid: false, error: `CVV must be ${expectedLength} digits` };
+    }
+
+    return { valid: true };
+}