@voxepay/checkout 0.0.1-security → 0.5.19

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @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,
+    VirtualAccountResponse,
+    PaymentStatusResponse,
+    DVAPaymentStatus,
+} from './api/client';
+
+// Default export for convenience
+export { VoxePay as default } from './voxepay';

package/src/types.ts

@@ -0,0 +1,178 @@
+/**
+ * VoxePay Checkout Type Definitions
+ */
+
+/**
+ * Configuration for initializing VoxePay
+ */
+export interface VoxePayConfig {
+    /** Optional API key (not required for public transfer/status flow) */
+    apiKey?: string;
+    /** Your VoxePay organization ID */
+    organizationId: string;
+    /** API base URL (defaults to https://devpay.voxepay.app) */
+    baseUrl?: string;
+    /** Public payment link slug used for bank transfer initiation endpoint */
+    paymentLinkSlug?: 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>;
+    /**
+     * Simulate webhook on payment status polling (useful for testing in dev/sandbox).
+     * When true, the API will trigger a simulated webhook on each status check.
+     */
+    simulateWebhook?: boolean;
+    /**
+     * Bypass key required when simulateWebhook is true.
+     * Only needed in sandbox/testing environments.
+     */
+    bypassKey?: string;
+}
+
+/**
+ * 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;
+    /** ISO timestamp when the virtual account expires (from API response) */
+    expiresAt?: string;
+    /** Fee details associated with this transfer */
+    feeDetails?: {
+        transactionFee?: number;
+        transactionFeeVat?: number;
+        totalFees: number;
+        grossAmount: number;
+        currency?: string;
+    };
+    /** Total amount to be paid including fees */
+    totalPayableAmount?: 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;
+    /** Customer's full name */
+    customerName?: string;
+    /** Additional metadata to attach to the payment */
+    metadata?: Record<string, unknown>;
+    /** Pre-calculated fee details if available */
+    feeDetails?: {
+        transactionFee?: number;
+        transactionFeeVat?: number;
+        totalFees: number;
+        grossAmount: number;
+        currency?: string;
+    };
+    /** 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;
+        paymentLinkSlug?: string;
+        simulateWebhook?: boolean;
+        bypassKey?: 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,198 @@
+/**
+ * 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 };
+}
+
+/**
+ * Validate card PIN
+ */
+export function validatePIN(pin: string): { valid: boolean; error?: string } {
+    const cleaned = pin.replace(/\s/g, '');
+
+    if (!cleaned) {
+        return { valid: false, error: 'PIN is required' };
+    }
+
+    if (!/^\d{4}$/.test(cleaned)) {
+        return { valid: false, error: 'PIN must be 4 digits' };
+    }
+
+    return { valid: true };
+}

package/src/utils/encryption.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure JavaScript RSA Encryption for card data
+ * No Node.js crypto dependency — works directly in the browser
+ * Uses native BigInt for correct RSA arithmetic (aligned with node-forge)
+ */
+
+// ============ Native BigInt helpers for RSA ============
+
+const _bigIntFromBytes = (bytes: number[]): bigint => {
+    let result = 0n;
+    for (const b of bytes) result = (result << 8n) | BigInt(b);
+    return result;
+};
+
+const _bigIntToBytes = (n: bigint, length: number): number[] => {
+    const bytes: number[] = [];
+    let rem = n;
+    while (rem > 0n) { bytes.unshift(Number(rem & 0xFFn)); rem >>= 8n; }
+    while (bytes.length < length) bytes.unshift(0);
+    return bytes;
+};
+
+const _bigIntModPow = (base: bigint, exp: bigint, mod: bigint): bigint => {
+    let result = 1n;
+    let b = base % mod;
+    while (exp > 0n) {
+        if (exp & 1n) result = (result * b) % mod;
+        exp >>= 1n;
+        b = (b * b) % mod;
+    }
+    return result;
+};
+
+
+/**
+ * Convert a string to its hex representation (matches node-forge reference)
+ */
+const toHex = (str: string): string => {
+    let hex = '';
+    for (let i = 0; i < str.length; i++) {
+        hex += str.charCodeAt(i).toString(16);
+    }
+    return hex;
+};
+
+/**
+ * Convert hex string to byte array
+ */
+const hexToBytes = (hex: string): number[] => {
+    const bytes: number[] = [];
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes.push(parseInt(hex.substring(i, i + 2), 16));
+    }
+    return bytes;
+};
+
+/**
+ * Convert byte array to base64 string
+ */
+const bytesToBase64 = (bytes: number[]): string => {
+    if (typeof btoa !== 'undefined') {
+        // Browser
+        return btoa(String.fromCharCode(...bytes));
+    }
+    // Node.js fallback
+    return Buffer.from(bytes).toString('base64');
+};
+
+
+// ============ PKCS#1 v1.5 Padding ============
+
+/**
+ * Apply PKCS#1 v1.5 type 2 padding for encryption
+ */
+const pkcs1Pad = (data: number[], keyByteLen: number): number[] => {
+    if (data.length > keyByteLen - 11) {
+        throw new Error('Message too long for RSA encryption');
+    }
+
+    const padLen = keyByteLen - data.length - 3;
+    const padded = new Array(keyByteLen);
+    padded[0] = 0x00;
+    padded[1] = 0x02;
+
+    // Fill with random non-zero bytes
+    for (let i = 0; i < padLen; i++) {
+        // Use crypto.getRandomValues if available, otherwise Math.random
+        let r = 0;
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            const arr = new Uint8Array(1);
+            while (r === 0) {
+                crypto.getRandomValues(arr);
+                r = arr[0];
+            }
+        } else {
+            while (r === 0) {
+                r = Math.floor(Math.random() * 255) + 1;
+            }
+        }
+        padded[2 + i] = r;
+    }
+
+    padded[2 + padLen] = 0x00;
+    for (let i = 0; i < data.length; i++) {
+        padded[3 + padLen + i] = data[i];
+    }
+
+    return padded;
+};
+
+// ============ RSA Encryption Config ============
+
+const RSA_CONFIG = {
+    modulus:
+        '009c7b3ba621a26c4b02f48cfc07ef6ee0aed8e12b4bd11c5cc0abf80d5206be69e1891e60fc88e2d565e2fabe4d0cf630e318a6c721c3ded718d0c530cdf050387ad0a30a336899bbda877d0ec7c7c3ffe693988bfae0ffbab71b25468c7814924f022cb5fda36e0d2c30a7161fa1c6fb5fbd7d05adbef7e68d48f8b6c5f511827c4b1c5ed15b6f20555affc4d0857ef7ab2b5c18ba22bea5d3a79bd1834badb5878d8c7a4b19da20c1f62340b1f7fbf01d2f2e97c9714a9df376ac0ea58072b2b77aeb7872b54a89667519de44d0fc73540beeaec4cb778a45eebfbefe2d817a8a8319b2bc6d9fa714f5289ec7c0dbc43496d71cf2a642cb679b0fc4072fd2cf',
+    publicExponent: '010001',
+};
+
+// ============ Public API ============
+
+export interface AuthDataParams {
+    version: string;
+    pan: string;
+    pin: string;
+    expiryDate: string;
+    cvv: string;
+}
+
+/**
+ * Generates encrypted auth data for card payment
+ * Uses pure JavaScript RSA — no Node.js crypto dependency
+ *
+ * @param params - Card details for encryption
+ * @returns Base64 encoded encrypted auth data
+ */
+export const generateAuthData = async ({
+    version,
+    pan,
+    pin,
+    expiryDate,
+    cvv,
+}: AuthDataParams): Promise<string> => {
+    try {
+        // Build auth string: "1Z{pan}Z{pin}Z{expDate}Z{cvv}" — matches node-forge reference
+        const authString = `${version}Z${pan}Z${pin}Z${expiryDate}Z${cvv}`;
+        const messageBytes = hexToBytes(toHex(authString));
+
+        // Parse RSA key and determine key byte length (strip leading zero byte)
+        const modulus = BigInt('0x' + RSA_CONFIG.modulus);
+        const exponent = BigInt('0x' + RSA_CONFIG.publicExponent);
+        const modHex = RSA_CONFIG.modulus.replace(/^0+/, '');
+        const keyByteLen = Math.ceil(modHex.length / 2);
+
+        // PKCS#1 v1.5 padding then RSA encrypt via native BigInt
+        const padded = pkcs1Pad(messageBytes, keyByteLen);
+        const m = _bigIntFromBytes(padded);
+        const c = _bigIntModPow(m, exponent, modulus);
+
+        return bytesToBase64(_bigIntToBytes(c, keyByteLen));
+    } catch (error) {
+        console.error('[VoxePay] Encryption error:', error);
+        throw new Error('Failed to encrypt card data');
+    }
+};
+
+/**
+ * Converts MM/YY format to YYMM format required by API
+ */
+export const formatExpiryForApi = (expiry: string): string => {
+    const cleaned = expiry.replace(/\s|\//g, '');
+    if (cleaned.length !== 4) return '';
+    const month = cleaned.substring(0, 2);
+    const year = cleaned.substring(2, 4);
+    return `${year}${month}`;
+};
+
+/**
+ * Removes spaces and formatting from PAN
+ */
+export const cleanPan = (pan: string): string => {
+    return pan.replace(/\s/g, '');
+};