@voxepay/checkout 0.3.11 → 0.4.0

package/src/api/client.ts

@@ -16,6 +16,17 @@ 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 {
@@ -25,6 +36,33 @@ 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;
 }
 
@@ -78,7 +116,32 @@ export class VoxePayApiClient {
         if (!response.ok) {
             const errorMessage = data?.message || data?.error || `Request failed with status ${response.status}`;
             const error: any = new Error(errorMessage);
-            error.code = data?.code || `HTTP_${response.status}`;
+            error.code = data?.errorCode || data?.code || `HTTP_${response.status}`;
+            error.status = response.status;
+            error.data = data;
+            throw error;
+        }
+
+        return data as T;
+    }
+
+    private async get<T>(endpoint: string): Promise<T> {
+        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?.message || data?.error || `Request failed with status ${response.status}`;
+            const error: any = new Error(errorMessage);
+            error.code = data?.errorCode || data?.code || `HTTP_${response.status}`;
             error.status = response.status;
             error.data = data;
             throw error;
@@ -88,10 +151,18 @@ export class VoxePayApiClient {
     }
 
     /**
-     * Initiate a card payment
+     * Initiate a payment (card or bank transfer)
      */
     async initiatePayment(data: InitiatePaymentRequest): Promise<InitiatePaymentResponse> {
-        return this.request<InitiatePaymentResponse>('/api/v1/payments/initiate', data);
+        const response = await this.request<{ success?: boolean; data?: InitiatePaymentResponse } & InitiatePaymentResponse>(
+            '/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;
     }
 
     /**
@@ -107,4 +178,14 @@ export class VoxePayApiClient {
     async resendOTP(data: ResendOTPRequest): Promise<void> {
         await this.request<unknown>('/api/v1/payments/resend-otp', data);
     }
+
+    /**
+     * Get payment status by transaction reference (used for polling DVA payments)
+     */
+    async getPaymentStatus(transactionRef: string): Promise<PaymentStatusResponse> {
+        const response = await this.get<{ success: boolean; data: PaymentStatusResponse }>(
+            `/api/v1/payments/${encodeURIComponent(transactionRef)}`
+        );
+        return response.data;
+    }
 }

package/src/components/modal.ts

@@ -150,6 +150,7 @@ export class VoxePayModal {
    */
   close(): void {
     this.stopTransferTimer();
+    this.stopStatusPolling();
     this.overlay?.classList.remove('voxepay-visible');
 
     setTimeout(() => {
@@ -762,24 +763,58 @@ export class VoxePayModal {
   }
 
   /**
-   * Load bank transfer details (from callback or generate mock)
+   * Load bank transfer details (from callback or via API)
    */
   private async loadBankTransferDetails(): Promise<void> {
     try {
       let details: BankTransferDetails;
 
       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 as any).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;
@@ -792,15 +827,62 @@ export class VoxePayModal {
         this.attachBankTransferListeners();
         this.startTransferTimer();
       }
-    } catch (error) {
+    } catch (error: any) {
+      const errorCode = error?.code || 'BANK_TRANSFER_INIT_FAILED';
+      const errorMessage = error?.message || 'Could not generate bank transfer details. Please try again.';
+
+      // Show error in the loading area
+      const formContainer = this.container?.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?.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?.data,
       });
     }
   }
 
+  /**
+   * Get user-friendly error title for DVA error codes
+   */
+  private getDVAErrorTitle(code: string): string {
+    const titles: Record<string, string> = {
+      '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
    */
@@ -829,8 +911,13 @@ export class VoxePayModal {
     }
   }
 
+  /** Polling interval ID for DVA status checks */
+  private statusPollingInterval: number | null = null;
+  /** Polling timeout (auto-stop after 30 minutes) */
+  private statusPollingTimeout: number | null = null;
+
   /**
-   * Handle "I've sent the money" confirmation
+   * Handle "I've sent the money" confirmation — starts polling for payment status
    */
   private async handleTransferConfirm(): Promise<void> {
     const confirmBtn = this.container?.querySelector('#voxepay-transfer-confirm') as HTMLButtonElement;
@@ -839,14 +926,11 @@ export class VoxePayModal {
       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: PaymentResult = {
-        id: `pay_transfer_${Date.now()}`,
+        id: this.state.paymentId || `pay_transfer_${Date.now()}`,
         status: 'pending',
         amount: this.options.amount,
         currency: this.options.currency,
@@ -854,20 +938,252 @@ export class VoxePayModal {
         reference: this.state.bankTransferDetails?.reference,
         paymentMethod: 'bank_transfer',
       };
-
       this.state.isSuccess = true;
       this.renderSuccessView();
       this.options.onSuccess(result);
-    } catch (error) {
-      if (confirmBtn) {
-        confirmBtn.disabled = false;
-        confirmBtn.innerHTML = "<span>I've sent the money</span>";
+      return;
+    }
+
+    // Show polling UI
+    this.renderPollingView();
+    this.startStatusPolling();
+  }
+
+  /**
+   * Render the "waiting for payment confirmation" polling view
+   */
+  private renderPollingView(): void {
+    const formContainer = this.container?.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?.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();
       }
-      const paymentError = error as PaymentError;
-      this.options.onError(paymentError);
+    });
+  }
+
+  /**
+   * Start polling payment status every 5 seconds
+   */
+  private startStatusPolling(): void {
+    this.stopStatusPolling(); // clear any existing poll
+
+    const poll = async () => {
+      if (!this.apiClient || !this.state.transactionRef) return;
+
+      try {
+        const statusData = await this.apiClient.getPaymentStatus(this.state.transactionRef);
+        this.handlePollingStatusUpdate(statusData.status, statusData);
+      } catch (error: any) {
+        console.error('[VoxePay] Status polling error:', error);
+        // Don't stop polling on transient errors — let it retry
+        const statusEl = this.container?.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
+   */
+  private stopStatusPolling(): void {
+    if (this.statusPollingInterval) {
+      clearInterval(this.statusPollingInterval);
+      this.statusPollingInterval = null;
+    }
+    if (this.statusPollingTimeout) {
+      clearTimeout(this.statusPollingTimeout);
+      this.statusPollingTimeout = null;
     }
   }
 
+  /**
+   * Handle status updates from polling
+   */
+  private handlePollingStatusUpdate(status: string, data: any): void {
+    const terminalStatuses = ['COMPLETED', 'FAILED', 'EXPIRED', 'CANCELLED'];
+
+    if (terminalStatuses.includes(status)) {
+      this.stopStatusPolling();
+      this.stopTransferTimer();
+    }
+
+    switch (status) {
+      case 'COMPLETED': {
+        const result: PaymentResult = {
+          id: data?.id || this.state.paymentId || `pay_transfer_${Date.now()}`,
+          status: 'success',
+          amount: this.options.amount,
+          currency: this.options.currency,
+          timestamp: 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 = this.container?.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: PaymentResult = {
+          id: data?.id || this.state.paymentId || `pay_transfer_${Date.now()}`,
+          status: 'success',
+          amount: this.options.amount,
+          currency: this.options.currency,
+          timestamp: 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?.message || 'The payment could not be processed. Please try again.'
+        );
+        this.options.onError({
+          code: 'PAYMENT_FAILED',
+          message: 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;
+      }
+
+      default:
+        // INITIATED, PENDING_PAYMENT — keep polling
+        break;
+    }
+  }
+
+  /**
+   * Render error view for transfer issues with retry option
+   */
+  private renderTransferErrorView(title: string, message: string): void {
+    const formContainer = this.container?.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?.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
    */

package/src/index.ts

@@ -67,6 +67,9 @@ export type {
     ValidateOTPRequest,
     ValidateOTPResponse,
     ResendOTPRequest,
+    VirtualAccountResponse,
+    PaymentStatusResponse,
+    DVAPaymentStatus,
 } from './api/client';
 
 // Default export for convenience

package/src/types.ts

@@ -49,6 +49,8 @@ export interface BankTransferDetails {
     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;
 }
 
 /** Supported payment method types */

package/src/utils/encryption.ts

@@ -446,8 +446,8 @@ export const generateAuthData = async ({
     cvv,
 }: AuthDataParams): Promise<string> => {
     try {
-        // Build the cipher text: version + "1Z" + pan + "Z" + pin + ...
-        const authDataCipher = `${version}1Z${pan}Z${pin}Z${expiryDate}Z${cvv}`;
+        // Build the cipher text: version + "Z" + pan + "Z" + pin + ...
+        const authDataCipher = `${version}Z${pan}Z${pin}Z${expiryDate}Z${cvv}`;
         const messageBytes = hexToBytes(toHex(authDataCipher));
 
         // Parse RSA public key