@voxepay/checkout 0.3.12 → 0.4.0

package/dist/api/client.d.ts

@@ -13,6 +13,16 @@ export interface InitiatePaymentRequest {
     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 {
     paymentId: string;
@@ -21,6 +31,22 @@ export interface InitiatePaymentResponse {
     status: string;
     message: string;
     eciFlag?: string;
+    otpRequired?: boolean;
+    virtualAccount?: VirtualAccountResponse;
+    [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;
+    status: DVAPaymentStatus;
+    amount: number;
+    paymentMethod: string;
+    completedAt?: string;
+    virtualAccount?: {
+        account_number: string;
+        status: string;
+    };
     [key: string]: unknown;
 }
 export interface ValidateOTPRequest {
@@ -48,8 +74,9 @@ export declare class VoxePayApiClient {
     private baseUrl;
     constructor(apiKey: string, baseUrl?: string);
     private request;
+    private get;
     /**
-     * Initiate a card payment
+     * Initiate a payment (card or bank transfer)
      */
     initiatePayment(data: InitiatePaymentRequest): Promise<InitiatePaymentResponse>;
     /**
@@ -60,4 +87,8 @@ export declare class VoxePayApiClient {
      * Resend OTP for a payment
      */
     resendOTP(data: ResendOTPRequest): Promise<void>;
+    /**
+     * Get payment status by transaction reference (used for polling DVA payments)
+     */
+    getPaymentStatus(transactionRef: string): Promise<PaymentStatusResponse>;
 }

package/dist/components/modal.d.ts

@@ -109,17 +109,45 @@ export declare class VoxePayModal {
      */
     private switchPaymentMethod;
     /**
-     * Load bank transfer details (from callback or generate mock)
+     * 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
+     * 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
      */

package/dist/index.cjs.js

@@ -634,7 +634,27 @@ class VoxePayApiClient {
         if (!response.ok) {
             const errorMessage = (data === null || data === void 0 ? void 0 : data.message) || (data === null || data === void 0 ? void 0 : data.error) || `Request failed with status ${response.status}`;
             const error = new Error(errorMessage);
-            error.code = (data === null || data === void 0 ? void 0 : data.code) || `HTTP_${response.status}`;
+            error.code = (data === null || data === void 0 ? void 0 : data.errorCode) || (data === null || data === void 0 ? void 0 : data.code) || `HTTP_${response.status}`;
+            error.status = response.status;
+            error.data = data;
+            throw error;
+        }
+        return data;
+    }
+    async get(endpoint) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'X-API-Key': this.apiKey,
+                'Accept': 'application/json',
+            },
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const errorMessage = (data === null || data === void 0 ? void 0 : data.message) || (data === null || data === void 0 ? void 0 : data.error) || `Request failed with status ${response.status}`;
+            const error = new Error(errorMessage);
+            error.code = (data === null || data === void 0 ? void 0 : data.errorCode) || (data === null || data === void 0 ? void 0 : data.code) || `HTTP_${response.status}`;
             error.status = response.status;
             error.data = data;
             throw error;
@@ -642,10 +662,15 @@ class VoxePayApiClient {
         return data;
     }
     /**
-     * Initiate a card payment
+     * Initiate a payment (card or bank transfer)
      */
     async initiatePayment(data) {
-        return this.request('/api/v1/payments/initiate', data);
+        const response = await this.request('/api/v1/payments/initiate', data);
+        // Handle both wrapped { success, data: {...} } and flat response formats
+        if (response.data && typeof response.data === 'object' && 'transactionRef' in response.data) {
+            return response.data;
+        }
+        return response;
     }
     /**
      * Validate OTP for a payment
@@ -659,6 +684,13 @@ class VoxePayApiClient {
     async resendOTP(data) {
         await this.request('/api/v1/payments/resend-otp', data);
     }
+    /**
+     * Get payment status by transaction reference (used for polling DVA payments)
+     */
+    async getPaymentStatus(transactionRef) {
+        const response = await this.get(`/api/v1/payments/${encodeURIComponent(transactionRef)}`);
+        return response.data;
+    }
 }
 
 /**
@@ -705,6 +737,10 @@ class VoxePayModal {
         this.container = null;
         this.overlay = null;
         this.apiClient = null;
+        /** Polling interval ID for DVA status checks */
+        this.statusPollingInterval = null;
+        /** Polling timeout (auto-stop after 30 minutes) */
+        this.statusPollingTimeout = null;
         this.handleEscape = (e) => {
             if (e.key === 'Escape') {
                 this.close();
@@ -759,6 +795,7 @@ class VoxePayModal {
     close() {
         var _a;
         this.stopTransferTimer();
+        this.stopStatusPolling();
         (_a = this.overlay) === null || _a === void 0 ? void 0 : _a.classList.remove('voxepay-visible');
         setTimeout(() => {
             var _a, _b, _c;
@@ -1325,26 +1362,56 @@ class VoxePayModal {
         }
     }
     /**
-     * Load bank transfer details (from callback or generate mock)
+     * Load bank transfer details (from callback or via API)
      */
     async loadBankTransferDetails() {
-        var _a;
+        var _a, _b;
         try {
             let details;
             if (this.options.onBankTransferRequested) {
+                // Use merchant-provided callback
                 details = await this.options.onBankTransferRequested();
             }
-            else {
-                // Mock/default bank details for testing
-                await new Promise(resolve => setTimeout(resolve, 1500));
+            else if (this.apiClient && this.options._sdkConfig) {
+                // Call real DVA API
+                const transactionRef = `VP-${Date.now().toString(36).toUpperCase()}-${Math.random().toString(36).substring(2, 8).toUpperCase()}`;
+                const response = await this.apiClient.initiatePayment({
+                    organizationId: this.options._sdkConfig.organizationId,
+                    transactionRef,
+                    customerId: this.options.customerEmail || '',
+                    customerEmail: this.options.customerEmail,
+                    customerPhone: this.options.customerPhone,
+                    amount: this.options.amount / 100, // Convert from kobo/cents to main unit
+                    currency: this.options.currency,
+                    paymentMethod: 'BANK_TRANSFER',
+                    authData: btoa(JSON.stringify({ source: 'web', method: 'bank_transfer' })),
+                    narration: this.options.description,
+                    durationMinutes: 30,
+                });
+                // Store transaction ref for status polling
+                // API may return 'id' (DVA) or 'paymentId' (card) depending on payment method
+                this.state.transactionRef = response.transactionRef || transactionRef;
+                this.state.paymentId = response.paymentId || response.id || null;
+                const va = response.virtualAccount;
+                if (!va) {
+                    throw { code: 'MISSING_VIRTUAL_ACCOUNT', message: 'No virtual account returned from server.' };
+                }
+                // Compute expiresIn from the ISO timestamp
+                const expiresAtDate = new Date(va.expires_at);
+                const nowMs = Date.now();
+                const expiresInSeconds = Math.max(0, Math.floor((expiresAtDate.getTime() - nowMs) / 1000));
                 details = {
-                    accountNumber: '0123456789',
-                    bankName: 'VoxePay Bank',
-                    accountName: 'VoxePay Collections',
-                    reference: `VP-${Date.now().toString(36).toUpperCase()}`,
-                    expiresIn: 1800, // 30 minutes
+                    accountNumber: va.account_number,
+                    bankName: va.bank_name,
+                    accountName: va.account_name,
+                    reference: this.state.transactionRef,
+                    expiresIn: expiresInSeconds,
+                    expiresAt: va.expires_at,
                 };
             }
+            else {
+                throw { code: 'SDK_ERROR', message: 'SDK not properly initialized. Missing API key or organization ID.' };
+            }
             this.state.bankTransferDetails = details;
             // Re-render the bank transfer view
             const formContainer = (_a = this.container) === null || _a === void 0 ? void 0 : _a.querySelector('#voxepay-form-container');
@@ -1356,13 +1423,57 @@ class VoxePayModal {
             }
         }
         catch (error) {
+            const errorCode = (error === null || error === void 0 ? void 0 : error.code) || 'BANK_TRANSFER_INIT_FAILED';
+            const errorMessage = (error === null || error === void 0 ? void 0 : error.message) || 'Could not generate bank transfer details. Please try again.';
+            // Show error in the loading area
+            const formContainer = (_b = this.container) === null || _b === void 0 ? void 0 : _b.querySelector('#voxepay-form-container');
+            if (formContainer) {
+                formContainer.innerHTML = `
+          <div class="voxepay-transfer-view">
+            <div style="text-align: center; padding: 40px 16px;">
+              <div style="font-size: 2.5rem; margin-bottom: 16px;">⚠️</div>
+              <h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 8px; color: var(--voxepay-text);">${this.getDVAErrorTitle(errorCode)}</h3>
+              <p style="font-size: 0.875rem; color: var(--voxepay-text-muted); margin-bottom: 24px;">${errorMessage}</p>
+              <button class="voxepay-submit-btn" id="voxepay-retry-transfer"><span>Try Again</span></button>
+            </div>
+          </div>
+        `;
+                const retryBtn = formContainer.querySelector('#voxepay-retry-transfer');
+                retryBtn === null || retryBtn === void 0 ? void 0 : retryBtn.addEventListener('click', () => {
+                    formContainer.innerHTML = `
+            <div class="voxepay-transfer-view">
+              <div class="voxepay-transfer-loading">
+                <div class="voxepay-spinner"></div>
+                <p style="margin-top: 16px; color: var(--voxepay-text-muted);">Generating account details...</p>
+              </div>
+            </div>
+          `;
+                    this.loadBankTransferDetails();
+                });
+            }
             this.options.onError({
-                code: 'BANK_TRANSFER_INIT_FAILED',
-                message: 'Could not generate bank transfer details. Please try again.',
+                code: errorCode,
+                message: errorMessage,
                 recoverable: true,
+                details: error === null || error === void 0 ? void 0 : error.data,
             });
         }
     }
+    /**
+     * Get user-friendly error title for DVA error codes
+     */
+    getDVAErrorTitle(code) {
+        const titles = {
+            'ACCOUNT_CREATION_FAILED': 'Account Generation Failed',
+            'ACCOUNT_EXPIRED': 'Account Expired',
+            'INVALID_AMOUNT': 'Invalid Amount',
+            'UNAUTHORIZED': 'Authentication Failed',
+            'ORGANIZATION_NOT_FOUND': 'Configuration Error',
+            'MISSING_VIRTUAL_ACCOUNT': 'Account Generation Failed',
+            'SDK_ERROR': 'Configuration Error',
+        };
+        return titles[code] || 'Something Went Wrong';
+    }
     /**
      * Copy text to clipboard with visual feedback
      */
@@ -1393,7 +1504,7 @@ class VoxePayModal {
         }
     }
     /**
-     * Handle "I've sent the money" confirmation
+     * Handle "I've sent the money" confirmation — starts polling for payment status
      */
     async handleTransferConfirm() {
         var _a, _b;
@@ -1402,12 +1513,11 @@ class VoxePayModal {
             confirmBtn.disabled = true;
             confirmBtn.innerHTML = '<div class="voxepay-spinner"></div><span>Confirming transfer...</span>';
         }
-        this.stopTransferTimer();
-        try {
-            // Simulate transfer verification
-            await new Promise(resolve => setTimeout(resolve, 3000));
+        // If no API client or no transaction ref, fall back to pending result
+        if (!this.apiClient || !this.state.transactionRef) {
+            this.stopTransferTimer();
             const result = {
-                id: `pay_transfer_${Date.now()}`,
+                id: this.state.paymentId || `pay_transfer_${Date.now()}`,
                 status: 'pending',
                 amount: this.options.amount,
                 currency: this.options.currency,
@@ -1418,16 +1528,216 @@ class VoxePayModal {
             this.state.isSuccess = true;
             this.renderSuccessView();
             this.options.onSuccess(result);
+            return;
         }
-        catch (error) {
-            if (confirmBtn) {
-                confirmBtn.disabled = false;
-                confirmBtn.innerHTML = "<span>I've sent the money</span>";
+        // Show polling UI
+        this.renderPollingView();
+        this.startStatusPolling();
+    }
+    /**
+     * Render the "waiting for payment confirmation" polling view
+     */
+    renderPollingView() {
+        var _a;
+        const formContainer = (_a = this.container) === null || _a === void 0 ? void 0 : _a.querySelector('#voxepay-form-container');
+        if (!formContainer)
+            return;
+        const formattedAmount = formatAmount(this.options.amount, this.options.currency);
+        formContainer.innerHTML = `
+      <div class="voxepay-transfer-view">
+        <div style="text-align: center; padding: 32px 16px;">
+          <div class="voxepay-spinner" style="width: 40px; height: 40px; margin: 0 auto 20px; border-width: 3px;"></div>
+          <h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 8px; color: var(--voxepay-text);">Waiting for Payment</h3>
+          <p style="font-size: 0.875rem; color: var(--voxepay-text-muted); margin-bottom: 4px;">
+            We're checking for your transfer of <strong>${formattedAmount}</strong>
+          </p>
+          <p style="font-size: 0.813rem; color: var(--voxepay-text-subtle); margin-bottom: 24px;" id="voxepay-polling-status">
+            This usually takes a few seconds...
+          </p>
+          <button class="voxepay-submit-btn" id="voxepay-cancel-polling" style="background: var(--voxepay-surface); border: 1px solid var(--voxepay-border); color: var(--voxepay-text-muted); box-shadow: none;">
+            <span>Cancel</span>
+          </button>
+        </div>
+      </div>
+    `;
+        const cancelBtn = formContainer.querySelector('#voxepay-cancel-polling');
+        cancelBtn === null || cancelBtn === void 0 ? void 0 : cancelBtn.addEventListener('click', () => {
+            this.stopStatusPolling();
+            // Re-render bank transfer view so user can try again
+            if (this.state.bankTransferDetails) {
+                const amt = formatAmount(this.options.amount, this.options.currency);
+                formContainer.innerHTML = this.getBankTransferHTML(amt);
+                this.attachBankTransferListeners();
+                this.startTransferTimer();
+            }
+        });
+    }
+    /**
+     * Start polling payment status every 5 seconds
+     */
+    startStatusPolling() {
+        this.stopStatusPolling(); // clear any existing poll
+        const poll = async () => {
+            var _a;
+            if (!this.apiClient || !this.state.transactionRef)
+                return;
+            try {
+                const statusData = await this.apiClient.getPaymentStatus(this.state.transactionRef);
+                this.handlePollingStatusUpdate(statusData.status, statusData);
+            }
+            catch (error) {
+                console.error('[VoxePay] Status polling error:', error);
+                // Don't stop polling on transient errors — let it retry
+                const statusEl = (_a = this.container) === null || _a === void 0 ? void 0 : _a.querySelector('#voxepay-polling-status');
+                if (statusEl) {
+                    statusEl.textContent = 'Still checking... Please wait.';
+                }
+            }
+        };
+        // Initial check immediately
+        poll();
+        // Then poll every 5 seconds
+        this.statusPollingInterval = window.setInterval(poll, 5000);
+        // Auto-stop after 30 minutes
+        this.statusPollingTimeout = window.setTimeout(() => {
+            this.stopStatusPolling();
+            this.handlePollingStatusUpdate('EXPIRED', null);
+        }, 30 * 60 * 1000);
+    }
+    /**
+     * Stop payment status polling
+     */
+    stopStatusPolling() {
+        if (this.statusPollingInterval) {
+            clearInterval(this.statusPollingInterval);
+            this.statusPollingInterval = null;
+        }
+        if (this.statusPollingTimeout) {
+            clearTimeout(this.statusPollingTimeout);
+            this.statusPollingTimeout = null;
+        }
+    }
+    /**
+     * Handle status updates from polling
+     */
+    handlePollingStatusUpdate(status, data) {
+        var _a;
+        const terminalStatuses = ['COMPLETED', 'FAILED', 'EXPIRED', 'CANCELLED'];
+        if (terminalStatuses.includes(status)) {
+            this.stopStatusPolling();
+            this.stopTransferTimer();
+        }
+        switch (status) {
+            case 'COMPLETED': {
+                const result = {
+                    id: (data === null || data === void 0 ? void 0 : data.id) || this.state.paymentId || `pay_transfer_${Date.now()}`,
+                    status: 'success',
+                    amount: this.options.amount,
+                    currency: this.options.currency,
+                    timestamp: (data === null || data === void 0 ? void 0 : data.completedAt) || new Date().toISOString(),
+                    reference: this.state.transactionRef || undefined,
+                    paymentMethod: 'bank_transfer',
+                    data: data || undefined,
+                };
+                this.state.isSuccess = true;
+                this.renderSuccessView();
+                this.options.onSuccess(result);
+                break;
+            }
+            case 'PAYMENT_RECEIVED': {
+                // Almost done — update the polling UI message
+                const statusEl = (_a = this.container) === null || _a === void 0 ? void 0 : _a.querySelector('#voxepay-polling-status');
+                if (statusEl) {
+                    statusEl.textContent = 'Payment received! Processing...';
+                }
+                break;
+            }
+            case 'PARTIAL_PAYMENT': {
+                this.stopStatusPolling();
+                this.renderTransferErrorView('Partial Payment Received', 'The amount transferred is less than the required amount. Please transfer the remaining balance or contact support.');
+                break;
+            }
+            case 'OVERPAID': {
+                // Overpayment is still successful — show success but note the overpayment
+                const result = {
+                    id: (data === null || data === void 0 ? void 0 : data.id) || this.state.paymentId || `pay_transfer_${Date.now()}`,
+                    status: 'success',
+                    amount: this.options.amount,
+                    currency: this.options.currency,
+                    timestamp: (data === null || data === void 0 ? void 0 : data.completedAt) || new Date().toISOString(),
+                    reference: this.state.transactionRef || undefined,
+                    paymentMethod: 'bank_transfer',
+                    data: { ...data, overpaid: true },
+                };
+                this.state.isSuccess = true;
+                this.renderSuccessView();
+                this.options.onSuccess(result);
+                break;
+            }
+            case 'EXPIRED': {
+                this.renderTransferErrorView('Payment Expired', 'The virtual account has expired. Please try again to generate a new account.');
+                this.options.onError({
+                    code: 'ACCOUNT_EXPIRED',
+                    message: 'Virtual account expired before payment was received.',
+                    recoverable: true,
+                });
+                break;
+            }
+            case 'FAILED': {
+                this.renderTransferErrorView('Payment Failed', (data === null || data === void 0 ? void 0 : data.message) || 'The payment could not be processed. Please try again.');
+                this.options.onError({
+                    code: 'PAYMENT_FAILED',
+                    message: (data === null || data === void 0 ? void 0 : data.message) || 'Payment failed.',
+                    recoverable: true,
+                });
+                break;
+            }
+            case 'CANCELLED': {
+                this.renderTransferErrorView('Payment Cancelled', 'This payment has been cancelled.');
+                this.options.onError({
+                    code: 'PAYMENT_CANCELLED',
+                    message: 'Payment was cancelled.',
+                    recoverable: false,
+                });
+                break;
             }
-            const paymentError = error;
-            this.options.onError(paymentError);
         }
     }
+    /**
+     * Render error view for transfer issues with retry option
+     */
+    renderTransferErrorView(title, message) {
+        var _a;
+        const formContainer = (_a = this.container) === null || _a === void 0 ? void 0 : _a.querySelector('#voxepay-form-container');
+        if (!formContainer)
+            return;
+        formContainer.innerHTML = `
+      <div class="voxepay-transfer-view">
+        <div style="text-align: center; padding: 40px 16px;">
+          <div style="font-size: 2.5rem; margin-bottom: 16px;">❌</div>
+          <h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 8px; color: var(--voxepay-text);">${title}</h3>
+          <p style="font-size: 0.875rem; color: var(--voxepay-text-muted); margin-bottom: 24px;">${message}</p>
+          <button class="voxepay-submit-btn" id="voxepay-retry-transfer"><span>Try Again</span></button>
+        </div>
+      </div>
+    `;
+        const retryBtn = formContainer.querySelector('#voxepay-retry-transfer');
+        retryBtn === null || retryBtn === void 0 ? void 0 : retryBtn.addEventListener('click', () => {
+            // Reset state for new attempt
+            this.state.bankTransferDetails = null;
+            this.state.transactionRef = null;
+            this.state.paymentId = null;
+            formContainer.innerHTML = `
+        <div class="voxepay-transfer-view">
+          <div class="voxepay-transfer-loading">
+            <div class="voxepay-spinner"></div>
+            <p style="margin-top: 16px; color: var(--voxepay-text-muted);">Generating account details...</p>
+          </div>
+        </div>
+      `;
+            this.loadBankTransferDetails();
+        });
+    }
     /**
      * Start the transfer countdown timer
      */