@voxepay/checkout 0.0.1-security → 0.5.19

package/README.md

@@ -1,5 +1,142 @@
-# Security holding package
+# @voxepay/checkout
 
-This package contained malicious code and was removed from the registry by the npm security team. A placeholder was published to ensure users are not affected in the future.
+Modern, beautiful payment checkout modal for the web by **VoxePay**.
+
+## Installation
+
+```bash
+npm install @voxepay/checkout
+```
+
+## Quick Start
+
+### Via Script Tag (CDN)
+
+```html
+<script src="https://unpkg.com/@voxepay/checkout/dist/voxepay-checkout.min.js"></script>
+<script>
+  VoxePay.init({ apiKey: 'pk_live_xxxxx' });
+
+  document.getElementById('pay-btn').addEventListener('click', () => {
+    VoxePay.checkout({
+      amount: 500000, // ₦5,000 in kobo
+      currency: 'NGN',
+      description: 'Premium Plan',
+      customerEmail: 'customer@example.com',
+      onSuccess: (result) => {
+        console.log('Payment successful!', result);
+      },
+      onError: (error) => {
+        console.error('Payment failed:', error.message);
+      },
+    });
+  });
+</script>
+```
+
+### Via ES Modules
+
+```javascript
+import { VoxePay } from '@voxepay/checkout';
+
+// Initialize once
+VoxePay.init({
+  apiKey: 'pk_live_xxxxx',
+  theme: 'dark', // 'dark' | 'light' | 'auto'
+});
+
+// Open checkout
+VoxePay.checkout({
+  amount: 500000, // Amount in kobo (₦5,000)
+  currency: 'NGN',
+  description: 'Premium Plan',
+  customerEmail: 'customer@example.com',
+  onSuccess: (result) => {
+    console.log('Paid!', result);
+  },
+  onError: (error) => {
+    console.error('Failed:', error.message);
+  },
+  onClose: () => {
+    console.log('Modal closed');
+  },
+});
+```
+
+## API Reference
+
+### `VoxePay.init(config)`
+
+Initialize the SDK. Call this once before using `checkout()`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiKey` | `string` | ✅ | Your VoxePay API key |
+| `theme` | `'dark' \| 'light' \| 'auto'` | ❌ | Theme mode (default: `'dark'`) |
+| `locale` | `string` | ❌ | Locale for formatting (default: `'en-US'`) |
+| `customStyles` | `Partial<VoxePayTheme>` | ❌ | Custom CSS variables |
+
+### `VoxePay.checkout(options)`
+
+Open the checkout modal.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `amount` | `number` | ✅ | Amount in smallest currency unit (kobo/cents) |
+| `currency` | `string` | ✅ | ISO 4217 currency code (e.g., `'NGN'`, `'USD'`) |
+| `description` | `string` | ❌ | Payment description shown in modal |
+| `customerEmail` | `string` | ❌ | Customer email for receipts |
+| `metadata` | `Record<string, unknown>` | ❌ | Additional metadata |
+| `onSuccess` | `(result: PaymentResult) => void` | ✅ | Success callback |
+| `onError` | `(error: PaymentError) => void` | ✅ | Error callback |
+| `onClose` | `() => void` | ❌ | Modal close callback |
+
+### `VoxePay.closeModal()`
+
+Programmatically close the checkout modal.
+
+### `VoxePay.setTheme(theme)`
+
+Change the theme dynamically.
+
+## Utilities
+
+```javascript
+import {
+  formatAmount,
+  getCurrencySymbol,
+  validateCardNumber,
+  detectCardBrand,
+} from '@voxepay/checkout';
+
+formatAmount(500000, 'NGN');        // "₦5,000.00"
+getCurrencySymbol('NGN');           // "₦"
+validateCardNumber('4111111111111111'); // { valid: true }
+detectCardBrand('4111111111111111');    // { name: 'Visa', code: 'visa', ... }
+```
+
+## Theming
+
+### Custom Colors
+
+```javascript
+VoxePay.init({
+  apiKey: 'pk_live_xxxxx',
+  customStyles: {
+    '--voxepay-primary': '#0061FF',
+    '--voxepay-secondary': '#0047CC',
+    '--voxepay-border-radius': '16px',
+  },
+});
+```
+
+## Supported Cards
+
+- Visa
+- Mastercard
+- Verve
+- American Express
+- Discover
+
+## License
 
-Please refer to www.npmjs.com/advisories?search=%40voxepay%2Fcheckout for more information.

package/dist/api/client.d.ts

@@ -0,0 +1,146 @@
+/**
+ * VoxePay Payment API Client
+ * Handles communication with the VoxePay payment gateway
+ */
+export interface InitiatePaymentRequest {
+    organizationId: string;
+    transactionRef: string;
+    customerId?: string;
+    customerEmail?: string;
+    customerPhone?: string;
+    customerName?: string;
+    amount: number;
+    currency: string;
+    paymentMethod: 'CARD' | 'BANK_TRANSFER';
+    authData: string;
+    narration?: string;
+    /** Virtual account validity in minutes (5-1440). Only for BANK_TRANSFER. Default: 30 */
+    durationMinutes?: number;
+}
+export interface VirtualAccountResponse {
+    account_number: string;
+    account_name: string;
+    bank_name: string;
+    bank_code: string;
+    expires_at: string;
+    status: string;
+}
+export interface InitiatePaymentResponse {
+    /** Backend sends `id` (not `paymentId`) for payment-links/public/.../pay */
+    id: string;
+    transactionRef: string;
+    status: string;
+    message: string;
+    /** Legacy field — some endpoints may still return this */
+    paymentId?: string;
+    transactionId?: string;
+    eciFlag?: string;
+    otpRequired?: boolean;
+    virtualAccount?: VirtualAccountResponse;
+    feeDetails?: {
+        transactionFee: number;
+        transactionFeeVat: number;
+        totalFees: number;
+        grossAmount: number;
+        currency: string;
+    };
+    [key: string]: unknown;
+}
+export type DVAPaymentStatus = 'INITIATED' | 'PENDING_PAYMENT' | 'PAYMENT_RECEIVED' | 'COMPLETED' | 'PARTIAL_PAYMENT' | 'OVERPAID' | 'EXPIRED' | 'FAILED' | 'CANCELLED';
+export interface PaymentStatusResponse {
+    id: string;
+    transactionRef: string;
+    customerId?: string;
+    amount: number;
+    currency: string;
+    paymentMethod: 'CARD' | 'BANK_TRANSFER';
+    status: DVAPaymentStatus;
+    paymentId?: string;
+    otpRequired?: boolean;
+    authorizationUrl?: string;
+    message?: string;
+    otpAttempts?: number;
+    maxOtpAttempts?: number;
+    createdAt: string;
+    completedAt?: string;
+    virtualAccount?: {
+        account_number: string;
+        account_name: string;
+        bank_name: string;
+        bank_code: string;
+        expires_at: string;
+        status: string;
+    };
+    feeDetails?: {
+        transactionFee: number;
+        transactionFeeVat: number;
+        totalFees: number;
+        grossAmount: number;
+        currency: string;
+    };
+}
+export interface ValidateOTPRequest {
+    paymentId: string;
+    otp: string;
+    /** Legacy field — some backends expect `transactionId` */
+    transactionId?: string;
+    /** Backend payment-links uses `transactionRef` as the identifier */
+    transactionRef?: string;
+    eciFlag?: string;
+    organizationId: string;
+}
+export interface ValidateOTPResponse {
+    status: string;
+    message: string;
+    paymentId: string;
+    transactionRef?: string;
+    amount?: number;
+    currency?: string;
+    [key: string]: unknown;
+}
+export interface ResendOTPRequest {
+    transactionRef: string;
+    organizationId: string;
+}
+export declare class VoxePayApiClient {
+    private apiKey?;
+    private bearerToken?;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string, bearerToken?: string);
+    /**
+     * Set Bearer token for authenticated endpoints (like getPaymentStatus)
+     */
+    setBearerToken(token: string): void;
+    private request;
+    private get;
+    /**
+     * Initiate payment (card or bank transfer) via public payment-link endpoint.
+     */
+    initiatePayment(paymentLinkSlug: string, data: InitiatePaymentRequest): Promise<InitiatePaymentResponse>;
+    /**
+     * @deprecated Use initiatePayment with a paymentLinkSlug instead.
+     */
+    initiateTransferPayment(paymentLinkSlug: string, data: InitiatePaymentRequest): Promise<InitiatePaymentResponse>;
+    /**
+     * Validate OTP for a payment
+     * @param slug - The payment link slug
+     * @param data - OTP validation payload
+     */
+    validateOTP(slug: string, data: ValidateOTPRequest): Promise<ValidateOTPResponse>;
+    /**
+     * Resend OTP for a payment
+     * @param slug - The payment link slug
+     * @param data - Resend OTP payload
+     */
+    resendOTP(slug: string, data: ResendOTPRequest): Promise<void>;
+    /**
+     * Get payment status by transaction reference (used for polling DVA payments)
+     * Uses public endpoint - no authentication required
+     * @param transactionRef - The transaction reference to check
+     * @param options - Optional query parameters (simulateWebhook, bypassKey)
+     */
+    getPaymentStatus(transactionRef: string, options?: {
+        simulateWebhook?: boolean;
+        bypassKey?: string;
+    }): Promise<PaymentStatusResponse>;
+}

package/dist/components/modal.d.ts

@@ -0,0 +1,190 @@
+/**
+ * VoxePay Checkout Modal Component
+ * A modern, glassmorphism payment modal
+ */
+import type { CheckoutOptions, BankTransferDetails, PaymentMethod } from '../types';
+export interface ModalState {
+    cardNumber: string;
+    expiry: string;
+    cvv: string;
+    pin: string;
+    otp: string;
+    errors: {
+        cardNumber?: string;
+        expiry?: string;
+        cvv?: string;
+        pin?: string;
+        otp?: string;
+    };
+    isProcessing: boolean;
+    isSuccess: boolean;
+    isOtpStep: boolean;
+    otpTimer: number;
+    canResendOtp: boolean;
+    otpTimerInterval: number | null;
+    paymentMethod: PaymentMethod;
+    transferTimer: number;
+    transferTimerInterval: number | null;
+    bankTransferDetails: BankTransferDetails | null;
+    paymentId: string | null;
+    transactionId: string | null;
+    transactionRef: string | null;
+    eciFlag: string | null;
+    otpDeliveryMessage: string | null;
+    feeDetails?: {
+        transactionFee: number;
+        transactionFeeVat: number;
+        totalFees: number;
+        grossAmount: number;
+        currency: string;
+    };
+}
+export declare class VoxePayModal {
+    private options;
+    private state;
+    private container;
+    private overlay;
+    private apiClient;
+    constructor(options: CheckoutOptions);
+    /**
+     * Open the checkout modal
+     */
+    open(): void;
+    /**
+     * Close the checkout modal
+     */
+    close(): void;
+    /**
+     * Inject styles if not already present
+     */
+    private injectStyles;
+    /**
+     * Render the modal HTML
+     */
+    private render;
+    /**
+     * Get available payment methods
+     */
+    private getPaymentMethods;
+    /**
+     * Get modal HTML
+     */
+    private getModalHTML;
+    /**
+     * Get card form HTML
+     */
+    private getCardFormHTML;
+    /**
+     * Get bank transfer HTML
+     */
+    private getBankTransferHTML;
+    /**
+     * Format countdown seconds to MM:SS
+     */
+    private formatCountdown;
+    /**
+     * Render success view
+     */
+    private renderSuccessView;
+    /**
+     * Render error modal view
+     */
+    private renderErrorModal;
+    /**
+     * Show error — inline for field errors, modal for fatal errors
+     */
+    private showErrorModal;
+    /**
+     * Render OTP verification view
+     */
+    private renderOTPView;
+    /**
+     * Attach OTP-specific event listeners
+     */
+    private attachOTPEventListeners;
+    private handleOTPInput;
+    private handleOTPKeydown;
+    private handleOTPPaste;
+    private updateOTPState;
+    private startOTPTimer;
+    private handleOTPSubmit;
+    private setOTPProcessing;
+    private verifyOTP;
+    private handleResendOTP;
+    private handleBackToCard;
+    /**
+     * Attach event listeners
+     */
+    private attachEventListeners;
+    /**
+     * Attach bank transfer specific event listeners
+     */
+    private attachBankTransferListeners;
+    /**
+     * Switch between payment methods
+     */
+    private switchPaymentMethod;
+    /**
+     * Load bank transfer details (from callback or via API)
+     */
+    private loadBankTransferDetails;
+    /**
+     * Get user-friendly error title for DVA error codes
+     */
+    private getDVAErrorTitle;
+    /**
+     * Copy text to clipboard with visual feedback
+     */
+    private copyToClipboard;
+    /** Polling interval ID for DVA status checks */
+    private statusPollingInterval;
+    /** Polling timeout (auto-stop after 30 minutes) */
+    private statusPollingTimeout;
+    /**
+     * Handle "I've sent the money" confirmation — starts polling for payment status
+     */
+    private handleTransferConfirm;
+    /**
+     * Render the "waiting for payment confirmation" polling view
+     */
+    private renderPollingView;
+    /**
+     * Start polling payment status every 5 seconds
+     */
+    private startStatusPolling;
+    /**
+     * Stop payment status polling
+     */
+    private stopStatusPolling;
+    /**
+     * Handle status updates from polling
+     */
+    private handlePollingStatusUpdate;
+    /**
+     * Render error view for transfer issues with retry option
+     */
+    private renderTransferErrorView;
+    /**
+     * Start the transfer countdown timer
+     */
+    private startTransferTimer;
+    /**
+     * Stop the transfer countdown timer
+     */
+    private stopTransferTimer;
+    private handleEscape;
+    private handleCardInput;
+    private handleExpiryInput;
+    private handleCVVInput;
+    private handlePinInput;
+    private validateField;
+    private showError;
+    private clearError;
+    private handleSubmit;
+    private setProcessing;
+    private processPayment;
+    /**
+     * Get VoxePay branded styles
+     */
+    private getStyles;
+}