react-native-fincra-checkout 1.0.0

package/src/types/index.ts

@@ -0,0 +1,165 @@
+import type { ReactNode } from 'react';
+
+// ─── Primitives ───────────────────────────────────────────────────────────────
+
+/**
+ * Currencies supported by the Fincra platform.
+ * Expands the Flutter enum (ngn, kes, ugx, ghs, zar, xaf, xof) with
+ * additional global currencies from the prompt spec.
+ */
+export const FincraCurrency = {
+  NGN: 'NGN',
+  USD: 'USD',
+  GBP: 'GBP',
+  EUR: 'EUR',
+  GHS: 'GHS',
+  KES: 'KES',
+  ZAR: 'ZAR',
+  UGX: 'UGX',
+  XAF: 'XAF',
+  XOF: 'XOF',
+} as const;
+
+export type FincraCurrency =
+  | 'NGN'
+  | 'USD'
+  | 'GBP'
+  | 'EUR'
+  | 'GHS'
+  | 'KES'
+  | 'ZAR'
+  | 'UGX'
+  | 'XAF'
+  | 'XOF';
+
+export const FeeBearer = {
+  Business: 'business',
+  Customer: 'customer',
+  business: 'business',
+  customer: 'customer',
+} as const;
+
+export type FeeBearer = 'business' | 'customer';
+
+// ─── Payment Data Models ───────────────────────────────────────────────────────
+
+/** Normalized successful payment response. */
+export interface FincraPaymentResponse {
+  /** Merchant/customer reference — mirrors Flutter's `FincraPaymentResponse.reference`. */
+  reference: string;
+  /** Fincra internal transaction ID. */
+  transactionId: string;
+  /** Payment status string (e.g., 'success', 'failed'). */
+  status: string;
+  /** Optional human-readable message from Fincra. */
+  message?: string;
+  /**
+   * Full raw response map. All values are strings.
+   * For inline mode, numeric/boolean fields from Fincra (e.g. `amount`) are
+   * coerced to strings to match the URL-params format used in WebView mode.
+   */
+  rawResponse: Record<string, string>;
+}
+
+/** Structured payment error. */
+export interface FincraPaymentError {
+  /** Error code string (e.g., 'timeout', 'cancelled', HTTP status code). */
+  code: string;
+  /** Human-readable error description. */
+  message: string;
+}
+
+// ─── Result Discriminated Union ────────────────────────────────────────────────
+
+/**
+ * All possible outcomes of a Fincra Checkout session.
+ * Use `result.type` to discriminate:
+ *
+ * @example
+ * ```typescript
+ * switch (result.type) {
+ *   case 'success':   handleSuccess(result.response); break;
+ *   case 'error':     handleError(result.error);       break;
+ *   case 'cancelled': handleCancelled();               break;
+ * }
+ * ```
+ */
+export type FincraCheckoutResult =
+  | { type: 'success'; response: FincraPaymentResponse }
+  | { type: 'error'; error: FincraPaymentError }
+  | { type: 'cancelled' };
+
+// ─── Component Props ───────────────────────────────────────────────────────────
+
+/** Shared props across both checkout modes. */
+export interface BaseCheckoutProps {
+  /** Called when payment is successfully completed. */
+  onSuccess?: (response: FincraPaymentResponse) => void;
+  /** Called when the payment fails or encounters an error. */
+  onFailed?: (error: FincraPaymentError) => void;
+  /** Called when the user cancels/closes the checkout. */
+  onCancelled?: () => void;
+  /** Title shown in the navigation header. Defaults to 'Secure Checkout'. */
+  headerTitle?: string;
+  /** Background color of the navigation header bar. */
+  headerBackgroundColor?: string;
+  /**
+   * Text/icon color inside the navigation header.
+   * Also determines the status bar style:
+   * - `'#000000'` (default) → `dark-content` status bar icons
+   * - Any other value → `light-content` status bar icons
+   */
+  headerTintColor?: string;
+  /** If true, shows a confirmation dialog before dismissing. Default: false. */
+  showCancelConfirmationDialog?: boolean;
+  /** Custom loading indicator to display while the WebView is loading. */
+  loadingComponent?: ReactNode;
+  /** Custom close icon/element for the header. */
+  closeIcon?: ReactNode;
+  /** Custom error screen renderer for network/loading recovery. */
+  renderError?: (
+    error: { code: string; message: string },
+    retry: () => void
+  ) => ReactNode;
+}
+
+/** Configuration for the WebView-based checkout (backend-generated URL). */
+export interface WebViewCheckoutConfig extends BaseCheckoutProps {
+  /**
+   * The backend-generated Fincra checkout URL.
+   * Generate this server-side using the Fincra API with your **secret key**.
+   * Never generate this on the client.
+   */
+  checkoutUrl: string;
+  /**
+   * Your backend redirect URL. When Fincra navigates to this URL,
+   * the SDK intercepts and resolves the payment result.
+   * If omitted, the SDK falls back to detecting `status` + `reference` query params.
+   */
+  redirectUrl?: string;
+}
+
+/** Configuration for the Inline JavaScript checkout (frontend-initiated). */
+export interface InlineCheckoutConfig extends BaseCheckoutProps {
+  /**
+   * Your Fincra **public key** (starts with `pk_`).
+   * @security Never use your secret key in mobile app code.
+   */
+  publicKey: string;
+  /** Amount to charge in the smallest currency unit (e.g., kobo for NGN). */
+  amount: number;
+  /** Currency for the transaction. */
+  currency: FincraCurrency;
+  /** Customer's email address. */
+  customerEmail: string;
+  /** Customer's full name. */
+  customerName: string;
+  /** Customer's phone number. */
+  customerPhoneNumber: string;
+  /** Who bears the Fincra processing fee. */
+  feeBearer: FeeBearer;
+  /** Optional unique transaction reference. Fincra generates one if omitted. */
+  reference?: string;
+  /** Restrict checkout to specific payment methods (e.g., ['card', 'bank_transfer']). */
+  paymentMethods?: string[];
+}

package/src/utils/UrlHandler.ts

@@ -0,0 +1,124 @@
+import type { FincraPaymentResponse } from '../types';
+
+// ─── URL Handler ──────────────────────────────────────────────────────────────
+//
+// Direct TypeScript port of flutter_fincra_checkout/lib/src/utils/url_handler.dart
+// Mirrors UrlHandler.isCompletionUrl() and UrlHandler.extractResponseParams()
+
+/**
+ * Utilities for detecting Fincra payment completion URLs and
+ * extracting normalized response parameters.
+ */
+export class UrlHandler {
+  /**
+   * Returns `true` if the given URL signals a Fincra payment completion.
+   *
+   * Logic (mirrors Flutter):
+   * 1. If `expectedRedirectUrl` is provided, check `url.startsWith(expectedRedirectUrl)`.
+   * 2. Fallback: Fincra appends `status` (or `payment_status`) AND `reference` as query params.
+   *
+   * @param url - The URL being navigated to.
+   * @param expectedRedirectUrl - The redirect URL you registered on your backend.
+   */
+  static isCompletionUrl(url: string, expectedRedirectUrl?: string): boolean {
+    if (!url) return false;
+
+    if (expectedRedirectUrl && expectedRedirectUrl.length > 0) {
+      return url.startsWith(expectedRedirectUrl);
+    }
+
+    // Fallback: detect via query parameters
+    try {
+      const params = UrlHandler._parseQueryParams(url);
+      const hasStatus =
+        params.has('status') || params.has('payment_status');
+      const hasReference = params.has('reference');
+      return hasStatus && hasReference;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Extracts all query parameters from the URL as a `Record<string, string>`.
+   *
+   * @param url - The completion URL from Fincra.
+   */
+  static extractResponseParams(url: string): Record<string, string> {
+    try {
+      const params = UrlHandler._parseQueryParams(url);
+      const result: Record<string, string> = {};
+      params.forEach((value, key) => {
+        result[key] = value;
+      });
+      return result;
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Builds a normalized `FincraPaymentResponse` from URL query parameters.
+   *
+   * Mirrors `FincraPaymentResponse.fromUrlParams()` in Flutter, including
+   * the reference normalization logic (customerReference → merchantReference → reference).
+   *
+   * @param params - Raw query params extracted from the completion URL.
+   */
+  static parsePaymentResponse(
+    params: Record<string, string>
+  ): FincraPaymentResponse {
+    // Fincra sometimes returns the merchant ref under different keys
+    const customRef =
+      params['customerReference'] ?? params['merchantReference'];
+    const internalRef =
+      params['transactionReference'] ?? params['transactionId'];
+
+    const finalRef = customRef ?? params['reference'] ?? '';
+    const finalTxId =
+      internalRef ?? (customRef != null ? params['reference'] ?? '' : '');
+
+    return {
+      reference: finalRef,
+      transactionId: finalTxId ?? '',
+      status: params['status'] ?? 'unknown',
+      message: params['message'],
+      rawResponse: params,
+    };
+  }
+
+  /**
+   * Determines if a status string represents a successful payment.
+   *
+   * @param status - The raw status string from Fincra.
+   */
+  static isSuccessStatus(status: string): boolean {
+    const normalized = status.toLowerCase().trim();
+    return normalized === 'success' || normalized === 'successful';
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────────
+
+  /**
+   * Parses URL query string into a `URLSearchParams`-like `Map`.
+   * Works in React Native (no DOM `URL` API available).
+   */
+  private static _parseQueryParams(url: string): Map<string, string> {
+    const map = new Map<string, string>();
+    const queryStart = url.indexOf('?');
+    if (queryStart === -1) return map;
+
+    const queryString = url.slice(queryStart + 1);
+    const pairs = queryString.split('&');
+
+    for (const pair of pairs) {
+      const eqIdx = pair.indexOf('=');
+      if (eqIdx === -1) continue;
+      const key = decodeURIComponent(pair.slice(0, eqIdx).replace(/\+/g, ' '));
+      const val = decodeURIComponent(pair.slice(eqIdx + 1).replace(/\+/g, ' '));
+      if (key) map.set(key, val);
+    }
+
+    return map;
+  }
+}