epic-collection-gateway-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 naderepic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# Epic Pay Collection Payment Gateway SDK (Demo)
+
+A lightweight demo SDK exposing a payment sheet with three flows: Pay by Card, Pay by Bank, and Pay by Epic Pay. Intended for integration demos and sandbox presentations.
+
+## Features
+
+- Minimal, framework-agnostic checkout modal
+- Three demo payment methods: `card`, `bank`, `epic`
+- Simple event callbacks via `onEvent`
+- Zero backend required (simulated success/failure)
+
+## Installation
+
+Published name: `epic-pay-sdk` (demo).
+
+Install from npm:
+
+```bash
+npm i epic-pay-sdk
+```
+
+## Quick start
+
+```ts
+import { initEpicPay, openPaymentSheet } from "epic-pay-sdk";
+
+initEpicPay({ environment: "sandbox" });
+
+// Trigger at checkout
+const result = await openPaymentSheet({ amount: 999, currency: "₦" });
+if (result.status === "succeeded") {
+  console.log("Paid", result.transactionId);
+}
+```
+
+## Usage
+
+### ESM (bundlers like Vite, Webpack, Next.js)
+
+```ts
+import EpicPay, {
+  initEpicPay,
+  openPaymentSheet,
+  closePaymentSheet,
+} from "epic-pay-sdk";
+
+initEpicPay({
+  merchantId: "demo_merchant_123",
+  environment: "sandbox",
+  onEvent: (e) => console.log("[EpicPay event]", e),
+});
+
+// On checkout
+const result = await openPaymentSheet({
+  amount: 999,
+  currency: "₦",
+  paymentMethods: ["card", "bank", "epic"],
+});
+if (result.status === "succeeded") {
+  console.log("Paid", result.transactionId);
+}
+
+// You can programmatically close the sheet if needed
+closePaymentSheet();
+```
+
+### Vanilla JS (no framework)
+
+Import via your bundler/ESM pipeline and call from regular scripts:
+
+```js
+import { initEpicPay, openPaymentSheet, closePaymentSheet } from "epic-pay-sdk";
+
+initEpicPay({ environment: "sandbox" });
+document.getElementById("pay-btn").addEventListener("click", async () => {
+  try {
+    const res = await openPaymentSheet({ amount: 500, currency: "₦" });
+    console.log(res);
+  } catch (err) {
+    console.error(err);
+  }
+});
+```
+
+## API
+
+- **`initEpicPay(options)`**
+
+  - `merchantId?: string`
+  - `environment?: 'sandbox' | 'production'` (default: `sandbox`)
+  - `onEvent?: (event) => void` event callback
+
+- **`openPaymentSheet(params)` -> `Promise<PaymentResult>`**
+
+  - `amount: number` (required)
+  - `currency?: string` (default: `₦`)
+  - `customer?: Record<string, any>`
+  - `paymentMethods?: ('card' | 'bank' | 'epic')[]` (default: all)
+
+  Notes:
+
+  - Must be called in a browser environment (uses DOM to render a modal sheet).
+  - Prevents multiple concurrent sheets; rejects if one is already open.
+
+- **`closePaymentSheet()`** closes the sheet.
+
+### Events
+
+Events emitted to `onEvent`:
+
+- `payment_opened`
+- `payment_initiated`
+- `payment_succeeded`
+- `payment_failed`
+- `payment_closed`
+
+## TypeScript
+
+Type definitions are included at `epic-pay-sdk/index.d.ts`.
+
+- `EpicPayInitOptions`
+- `OpenPaymentSheetParams`
+- `PaymentResult` union with `succeeded | cancelled | failed`
+
+Importing with types:
+
+```ts
+import type { OpenPaymentSheetParams, PaymentResult } from "epic-pay-sdk";
+```
+
+## Demo app
+
+A simple integration demo is available in this repo at `epic-demo/`.
+
+## Notes
+
+- This is a front-end only demo. No real payments are processed.
+- Success is simulated (~90% chance).
+- Styles are injected dynamically by the SDK.
+
+## Redirect-only integration (new flow)
+
+If you want a redirect-only flow (the SDK only performs the redirect to your hosted portal and helps parse the return), initialize with `redirectUrl` and optional `clientId`/`clientSecret`:
+
+```ts
+import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl } from 'epic-pay-sdk';
+
+initEpicPay({
+  redirectUrl: 'https://pay.your-portal.com/checkout',
+  clientId: 'your_public_client_id',
+});
+
+// When user clicks "Proceed to pay" on the integrator page:
+redirectToPortal({
+  amount: 2300,
+  currency: 'NGN',
+  customerEmail: 'user@example.com', // optional
+  sessionId: 'sess_123456789',
+  returnUrl: 'https://merchant.example.com/order-success',
+});
+
+// On your returnUrl page, parse the response:
+const res = parsePaymentResponseFromUrl();
+// res may contain: sessionId, paymentRef, status, and any other keys your portal includes
+console.log(res);
+```
+
+## License
+
+MIT
+
+---
+
+## Epic Collections Web Checkout integration (React example)
+
+This is a concrete example of how a React storefront (like `eCommerceFE`) integrates with this SDK for the Epic Collections Web Checkout flow.
+
+### Example: Checkout button in a React header/cart component
+
+```tsx
+import { startEpicCollectionPayment } from '@naderepic/epic-collection-payment-gateway-sdk';
+
+function CheckoutButton({ cartItems }) {
+  const [paying, setPaying] = useState(false);
+  const total = cartItems.reduce((sum, i) => sum + i.price * i.quantity, 0);
+
+  const handleCheckout = async () => {
+    if (cartItems.length === 0) return;
+    try {
+      setPaying(true);
+      const sessionId = '2349283949994959000345340212778'; // generate per order in production
+
+      const url = await startEpicCollectionPayment({
+        clientId: '3cEePs32ipRTQkBRn0c33gAb7UOqcLPwMBMNhDgK',
+        clientSecret: 'mye008uvYFzqWUQEjLGBbIuWd8eEJmhSRUPy1IlmsZlCa84apHxNrsDGvSLVVL5z',
+        redirectUrl: 'https://your-site.com/order-result',
+        amount: total,
+        sessionId,
+        customerDetails: {
+          email: 'user@gmail.com',
+        },
+      });
+
+      window.location.assign(url);
+    } finally {
+      setPaying(false);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleCheckout}
+      disabled={cartItems.length === 0 || paying}
+    >
+      {paying ? 'Processing...' : `Proceed to Pay ( ₦${total.toFixed(2)})`}
+    </button>
+  );
+}
+```
+
+### Options passed from frontend to the SDK
+
+The options object passed to `startEpicCollectionPayment` has the following shape on the **frontend**:
+
+```json
+{
+  "clientId": "<clientId>",
+  "clientSecret": "<clientSecret>",
+  "redirectUrl": "https://your-site.com/order-result",
+  "amount": <amount>,
+  "sessionId": "<sessionId>",
+  "customerDetails": {
+    "email": "user@example.com"
+  }
+}
+```
+
+- `clientId`, `clientSecret` – provided by the Epic Collections Admin Portal.
+- `redirectUrl` – **merchant callback URL** where the shopper is sent back after payment/cancel.
+- `amount` – total amount for this checkout (computed from cart).
+- `sessionId` – unique per checkout session/order.
+- `customerDetails` – optional customer metadata forwarded as query params (`clientEmail`, `clientName`, `clientPhone`).
+
+The SDK uses this **frontend** payload to:
+- Call the Epic backend `/web-checkout/auth` with `clientId`, `clientSecret`, `sessionId`, `amount`, `redirectUrl`, and any `customerDetails`.
+- Build and return the final redirect URL for the **Collections payment portal** (from `VITE_PORTAL_URL` / `VITE_EPIC_COLLECTION_PORTAL_URL` inside the SDK), which your frontend then navigates to with `window.location.assign(url)` (or your router of choice).
+
+> Note: For this Epic Collections Web Checkout flow you **do not need to call `initEpicPay`**. The payment portal URL is resolved inside the SDK from environment variables.

package/dist/core/api.d.ts

@@ -0,0 +1,42 @@
+export type EpicPayEnvironment = 'sandbox' | 'production';
+export interface EpicPayInitOptions {
+    merchantId?: string;
+    environment?: EpicPayEnvironment;
+    onEvent?: (event: {
+        type: string;
+        payload?: any;
+        timestamp: number;
+    }) => void;
+    apiBase?: string;
+    headers?: Record<string, string>;
+    paymentMethodsUrl?: string;
+    theme?: Record<string, string>;
+    redirectUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface RedirectToPortalParams {
+    amount: number;
+    sessionId: string;
+    additionalParams?: Record<string, string | number | boolean>;
+    redirectUrl?: string;
+    customerDetails?: EpicCollectioncustomerDetails;
+}
+export interface EpicCollectioncustomerDetails {
+    name?: string;
+    email?: string;
+    phone?: string;
+}
+export interface StartEpicCollectionPaymentOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Merchant callback URL where the shopper is sent back after payment/cancel */
+    redirectUrl: string;
+    amount: number;
+    sessionId: string;
+    customerDetails?: EpicCollectioncustomerDetails;
+}
+export declare function redirectToPortal(params: RedirectToPortalParams): string;
+export declare function startEpicCollectionPayment(options: StartEpicCollectionPaymentOptions): Promise<string>;
+export declare function parsePaymentResponseFromUrl(raw?: string): Record<string, string>;
+export declare function initEpicPay(options?: EpicPayInitOptions): void;

package/dist/core/epicConfig.d.ts

@@ -0,0 +1,5 @@
+import { EpicPayConfig } from './types';
+
+export declare const epicConfig: EpicPayConfig;
+export declare function setConfig(config: Partial<EpicPayConfig>): void;
+export declare function emit(type: string, payload?: any): void;

package/dist/core/types.d.ts

@@ -0,0 +1,61 @@
+export interface EpicPayConfig {
+    environment?: 'sandbox' | 'production' | string;
+    apiBase?: string;
+    headers?: Record<string, string>;
+    /** Full URL to the hosted payment portal for redirect flow */
+    redirectUrl?: string;
+    /** Optional client id provided to integrator page */
+    clientId?: string;
+    /** Optional client secret provided to integrator page */
+    clientSecret?: string;
+    /** If true, do not actually redirect; only log what would happen. */
+    dryRun?: boolean;
+    onEvent?: (event: PaymentEvent) => void;
+}
+export interface ThemeConfig {
+    colorPrimaryViolet?: string;
+    borderColor?: string;
+    fontColor?: string;
+    black?: string;
+    white?: string;
+    inputBackground?: string;
+    tabBackground?: string;
+}
+export interface PaymentMethod {
+    identityKey: string;
+    methodName: string;
+    icon?: string;
+}
+export interface PaymentSheetProps {
+    amount: number;
+    currency?: string;
+    customer?: CustomerInfo;
+    paymentMethods?: PaymentMethod[] | 'auto';
+    onSuccess?: (result: PaymentResult) => void;
+    onError?: (error: PaymentError) => void;
+    onClose?: () => void;
+}
+export interface CustomerInfo {
+    id?: string;
+    email?: string;
+    name?: string;
+    phone?: string;
+}
+export interface PaymentResult {
+    status: 'succeeded' | 'failed' | 'cancelled';
+    method?: string;
+    amount?: number;
+    currency?: string;
+    transactionId?: string;
+    error?: string;
+}
+export interface PaymentError {
+    status: 'failed';
+    method?: string;
+    error: string;
+}
+export interface PaymentEvent {
+    type: string;
+    payload: any;
+    timestamp: number;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
+export { setConfig, epicConfig } from './core/epicConfig';
+export * from './core/types';
+export { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
+export type { EpicPayInitOptions, EpicPayEnvironment } from './core/api';
+export type { RedirectToPortalParams, StartEpicCollectionPaymentOptions, EpicCollectioncustomerDetails } from './core/api';
+declare const EpicCollectionSdk: {
+    initEpicPay: typeof initEpicPay;
+    redirectToPortal: typeof redirectToPortal;
+    parsePaymentResponseFromUrl: typeof parsePaymentResponseFromUrl;
+    startEpicCollectionPayment: typeof startEpicCollectionPayment;
+};
+export default EpicCollectionSdk;

package/dist/index.js

@@ -0,0 +1,114 @@
+const f = { BASE_URL: "/", MODE: "production", DEV: !1, PROD: !0, SSR: !1 }, m = f.VITE_PORTAL_URL || "https://collections.epicpay.co/web-checkout", E = f.VITE_PORTAL_URL || "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", y = f.VITE_EPIC_ENVIRONMENT || "", s = {
+  environment: y,
+  apiBase: E,
+  headers: {},
+  redirectUrl: m,
+  clientId: "",
+  clientSecret: "",
+  dryRun: !0,
+  onEvent: void 0
+};
+function p(e) {
+  Object.assign(s, e);
+}
+function u(e) {
+  const { amount: n, sessionId: i, additionalParams: c, redirectUrl: o } = e, r = s.redirectUrl || s.apiBase;
+  if (!r)
+    throw new Error('No redirectUrl configured. Call initEpicPay({ redirectUrl: "https://..." }).');
+  const t = {
+    amount: String(n),
+    sessionId: i
+  };
+  o && (t.redirectUrl = String(o)), s.clientId && (t.clientId = s.clientId), s.clientSecret && (t.clientSecret = s.clientSecret), c && Object.keys(c).forEach((a) => {
+    t[a] = String(c[a]);
+  });
+  const l = Object.keys(t).map((a) => `${encodeURIComponent(a)}=${encodeURIComponent(t[a])}`).join("&"), h = r + (r.includes("?") ? "&" : "?") + l;
+  try {
+    console.log("[EpicPay] redirectToPortal", { portal: r, amount: n, sessionId: i });
+  } catch {
+  }
+  try {
+    console.log("[EpicPay] redirectToPortal URL:", h);
+  } catch {
+  }
+  return h;
+}
+async function g(e) {
+  const { clientId: n, clientSecret: i, redirectUrl: c, amount: o, sessionId: r, customerDetails: t } = e;
+  if (!n || typeof n != "string" || n.length < 16)
+    throw new Error("Invalid clientId");
+  if (!i || typeof i != "string" || i.length < 16)
+    throw new Error("Invalid clientSecret");
+  if (!r || typeof r != "string" || r.length < 16)
+    throw new Error("Invalid sessionId");
+  if (!c || typeof c != "string")
+    throw new Error("Invalid redirectUrl");
+  p({
+    clientId: n,
+    clientSecret: i
+  });
+  const l = s.apiBase;
+  if (!l)
+    throw new Error("No API base configured for authentication");
+  const h = (l.endsWith("/") ? l.slice(0, -1) : l) + "/web-checkout/auth", a = await fetch(h, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", grabbersbeware: "getthehellout989898" },
+    body: JSON.stringify({
+      clientId: n,
+      clientSecret: i,
+      sessionId: r,
+      amount: o,
+      redirectUrl: c,
+      customerDetails: t
+    })
+  });
+  if (!a.ok)
+    throw new Error("Authentication request failed");
+  try {
+    await a.json();
+  } catch {
+  }
+  const d = {};
+  return d.clientSecret = i, t && (t.name && (d.clientName = String(t.name)), t.email && (d.clientEmail = String(t.email)), t.phone && (d.clientPhone = String(t.phone))), u({
+    amount: o,
+    sessionId: r,
+    additionalParams: d,
+    redirectUrl: c
+  });
+}
+function w(e) {
+  const n = e ?? (typeof window < "u" ? window.location.search || window.location.hash : ""), i = n.startsWith("?") || n.startsWith("#") ? n.substring(1) : n, c = new URLSearchParams(i), o = {};
+  c.forEach((r, t) => {
+    o[t] = r;
+  });
+  try {
+    console.log("[EpicPay] parsePaymentResponseFromUrl", o);
+  } catch {
+  }
+  return o;
+}
+function I(e = {}) {
+  p({
+    environment: e.environment ?? "sandbox",
+    apiBase: e.apiBase,
+    headers: e.headers,
+    onEvent: e.onEvent,
+    redirectUrl: e.redirectUrl,
+    clientId: e.clientId,
+    clientSecret: e.clientSecret
+  });
+  try {
+    console.log("[EpicPay] initEpicPay", { environment: e.environment ?? "sandbox", redirectUrl: e.redirectUrl, clientId: e.clientId, clientSecret: e.clientSecret });
+  } catch {
+  }
+}
+const S = { initEpicPay: I, redirectToPortal: u, parsePaymentResponseFromUrl: w, startEpicCollectionPayment: g };
+export {
+  S as default,
+  s as epicConfig,
+  I as initEpicPay,
+  w as parsePaymentResponseFromUrl,
+  u as redirectToPortal,
+  p as setConfig,
+  g as startEpicCollectionPayment
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "epic-collection-gateway-sdk",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {},
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.2",
+    "vite": "^4.4.0",
+    "vite-plugin-dts": "^3.5.3"
+  }
+}