@mopay/node-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MoPay
+
+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,246 @@
+# MoPay Node SDK
+
+TypeScript SDK for creating and verifying MoPay hosted payment sessions from Node.js.
+
+MoPay's flow is:
+
+1. Create a payment session from your backend.
+2. Redirect the customer to the returned `paymentUrl`.
+3. When MoPay redirects the customer back, verify the final state with the session API.
+
+## Installation
+
+```sh
+pnpm add @mopay/node-sdk
+```
+
+## Usage
+
+```ts
+import { MoPay } from "@mopay/node-sdk";
+
+const mopay = new MoPay({
+  apiKey: process.env.MOPAY_API_KEY!,
+});
+
+const session = await mopay.createPaymentSession({
+  amount: "100.00",
+  reference: "ORDER12345",
+  redirectUrl: "https://yourwebsite.com/payment-complete",
+  description: "Order #12345",
+  customerEmail: "customer@example.com",
+  customerName: "John Doe",
+});
+
+console.log(session.paymentUrl);
+```
+
+## Browser Checkout
+
+Use the secret-key SDK only on the merchant backend. The frontend should receive a checkout URL or token from the merchant backend, then call `MoPayCheckout.open({ checkoutUrl })`.
+
+Merchant backend:
+
+```ts
+import { MoPay } from "@mopay/node-sdk";
+
+const mopay = new MoPay({
+  apiKey: process.env.MOPAY_API_KEY!,
+});
+
+const session = await mopay.createPaymentSession({
+  amount: "100.00",
+  reference: "ORDER12345",
+  redirectUrl: "https://yourwebsite.com/payment-complete",
+});
+
+return {
+  sessionId: session.sessionId,
+  checkoutUrl: session.paymentUrl,
+};
+```
+
+Merchant frontend:
+
+```js
+import { MoPayCheckout } from "@mopay/node-sdk";
+
+const session = await fetch("/api/create-mopay-checkout", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ amount: "100.00", reference: "ORDER12345" }),
+}).then((response) => response.json());
+
+MoPayCheckout.open({
+  checkoutUrl: session.checkoutUrl,
+  allowedOrigins: [window.location.origin],
+  width: 520,
+  height: 760,
+  resizable: true,
+  onSuccess: () => {
+    // UI feedback only. Do not deliver value here.
+  },
+  onClose: async () => {
+    await fetch(`/api/verify-mopay-session/${session.sessionId}`);
+  },
+});
+```
+
+Supported modes:
+
+- `dialog`: opens an iframe dialog inside your UI. This is the default.
+- `popup`: opens the hosted MoPay page in a centered browser popup.
+- `redirect`: sends the current page to `paymentUrl`.
+
+For dialog mode, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, and `maxHeight` control the SDK-owned frame around the hosted MoPay page. Set `resizable: true` if customers should be able to drag-resize the checkout frame.
+
+For iframe checkout, MoPay's hosted page must allow embedding from approved merchant sites. The MoPay checkout server should set `Content-Security-Policy: frame-ancestors ...` dynamically from the merchant's registered allowed origins and avoid `X-Frame-Options: DENY` or `SAMEORIGIN` for embeddable checkout pages.
+
+The SDK only accepts `postMessage` events from the checkout URL origin, and only from the opened iframe or popup window. Frontend callbacks are for UI feedback only; merchants must confirm payment through signed webhooks or `mopay.getTransaction(sessionId)` before delivering value.
+
+If your checkout iframe can redirect back to a merchant-owned completion page, pass that exact origin in `allowedOrigins`. The checkout URL origin is always trusted automatically.
+
+## Verify A Redirect
+
+Redirect parameters are useful for routing your user, but they should not be treated as the final source of truth. Always verify with MoPay from your backend.
+
+```ts
+import { MoPay, parseRedirect } from "@mopay/node-sdk";
+
+const redirect = parseRedirect(
+  "https://yourwebsite.com/payment-complete?status=success&reference=ORDER12345&transactionId=TXN123&sessionId=MOP_abc123_ORDER12345&amount=100.00&paymentMethod=mpesa",
+);
+
+const mopay = new MoPay({ apiKey: process.env.MOPAY_API_KEY! });
+const verified = await mopay.retrieveSession(redirect.sessionId);
+
+if (verified.session.status === "COMPLETED") {
+  // Fulfil the order.
+}
+```
+
+## API
+
+### `new MoPay(options)`
+
+```ts
+const mopay = new MoPay({
+  apiKey: "YOUR_API_KEY",
+  baseUrl: "https://mopay.co.ls",
+  timeoutMs: 30000,
+});
+```
+
+`apiKey` is required. `baseUrl` is optional and defaults to `https://mopay.co.ls`.
+
+### `mopay.createPaymentSession(params)`
+
+Creates a hosted payment session with `POST /api/external/payment`.
+
+Required fields:
+
+- `amount`: string or number, for example `"100.00"`.
+- `reference`: unique alphanumeric order reference, for example `"ORDER12345"`.
+- `redirectUrl`: absolute URL where MoPay should send the customer after payment.
+
+Optional fields:
+
+- `description`
+- `customerEmail`
+- `customerName`
+- `paymentFrequency`: `ONCE`, `MONTHLY`, or `ANNUALLY`
+- `productName`
+- `productDetails`
+- `productImage`
+- `payWhatYouWant`
+- `minimumAmount`
+
+### `mopay.retrieveSession(sessionId)`
+
+Retrieves session details with `GET /api/external/session/v1/{sessionId}`.
+
+### `mopay.parseRedirect(input)` or `parseRedirect(input)`
+
+Parses MoPay redirect query parameters from a URL, `URLSearchParams`, or plain object.
+
+### `MoPayCheckout.open({ checkoutUrl, ...options })`
+
+Opens the hosted checkout page in `popup`, `dialog`, or `redirect` mode.
+
+Accepts `checkoutUrl`, `checkout_url`, `checkoutToken`, or `checkout_token`. `checkoutUrl` is the same value as the documented `paymentUrl` returned by `createPaymentSession`.
+
+### `mopay.checkout(params, options)`
+
+Convenience method that creates a session and opens the checkout dialog. Use this only from a trusted environment because it requires the secret API key.
+
+### `mopay.getSession(sessionId)` / `mopay.getTransaction(sessionId)`
+
+Retrieves the latest MoPay session and transaction data for any session ID.
+
+### `mopay.isSuccessful(session)`
+
+Returns `true` when a retrieved session is completed or has `transactionStatus: "success"`.
+
+### `mopay.isPaymentSuccessful(sessionId)`
+
+Retrieves the session by ID and returns `true` when the payment is successful.
+
+### `mopay.waitForSession(sessionId, options)`
+
+Polls MoPay until a session reaches a terminal state such as `COMPLETED`, `FAILED`, `CANCELLED`, or `EXPIRED`.
+
+## Sandbox Mobile Money Numbers
+
+Use these only while your MoPay project is in sandbox mode.
+
+| Method | Number | Expected result |
+| --- | --- | --- |
+| M-Pesa | `52211111` | Immediate success |
+| M-Pesa | `52222222` | Pending first, then success |
+| M-Pesa | `52233333` | Failed |
+| M-Pesa | `52244444` | Cancelled |
+| M-Pesa | `52255555` | Expired |
+| EcoCash | `63211111` | Immediate success |
+| EcoCash | `63222222` | Pending first, then success |
+| EcoCash | `63233333` | Failed |
+| EcoCash | `63244444` | Cancelled |
+| EcoCash | `63255555` | Expired |
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+```
+
+## Simple HTML Example
+
+This repository includes an Express-backed checkout example outside the publishable SDK package.
+From the repository root:
+
+```sh
+cp examples/simple-checkout/.env.example examples/simple-checkout/.env
+pnpm example:simple-checkout
+```
+
+Open `http://127.0.0.1:4173/`.
+
+Put your real MoPay secret key in `examples/simple-checkout/.env`:
+
+```env
+MOPAY_API_KEY=sk_live_or_test_xxx
+```
+
+Optional environment variables:
+
+- `MOPAY_BASE_URL`: defaults to `https://mopay.co.ls`.
+- `MERCHANT_PUBLIC_URL`: public URL for the merchant demo, used to build the MoPay `redirectUrl`.
+- `MOPAY_REDIRECT_URL`: full redirect URL override.
+- `PORT`: defaults to `4173`.
+- `HOST`: defaults to `127.0.0.1`.
+
+The example serves a tiny merchant backend with Express:
+
+- `POST /api/create-mopay-checkout` creates a MoPay checkout session through `mopay.createPaymentSession`.
+- `GET /api/mopay-session/:sessionId` retrieves transaction data through `mopay.getTransaction`.
+- `GET /api/mopay-session/:sessionId/success` verifies whether the session is paid through `mopay.isSuccessful`.

package/dist/base.d.ts

@@ -0,0 +1,13 @@
+import type { CheckoutOptions, MoPayConfig, RequestOptions } from "./types.js";
+export declare abstract class Base {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl?;
+    private readonly userAgent;
+    private readonly checkoutOptions;
+    constructor(config: MoPayConfig);
+    protected getDefaultCheckoutOptions(): CheckoutOptions;
+    protected request<T>(endpoint: string, options?: RequestInit, requestOptions?: RequestOptions): Promise<T>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAGf,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAKpB,8BAAsB,IAAI;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,MAAM,EAAE,WAAW;IAa/B,SAAS,CAAC,yBAAyB,IAAI,eAAe;cAItC,OAAO,CAAC,CAAC,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,EACzB,cAAc,GAAE,cAAmB,GAClC,OAAO,CAAC,CAAC,CAAC;CAuDd"}

package/dist/base.js

@@ -0,0 +1,122 @@
+import { MoPayAPIError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://mopay.co.ls";
+const DEFAULT_TIMEOUT_MS = 30000;
+export class Base {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    userAgent;
+    checkoutOptions;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new MoPayAPIError("apiKey is required");
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = normalizeBaseUrl(config.baseUrl || DEFAULT_BASE_URL);
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = config.fetch || getNativeFetch();
+        this.userAgent = config.userAgent || "@mopay/node-sdk/0.1.0";
+        this.checkoutOptions = config.checkout || {};
+    }
+    getDefaultCheckoutOptions() {
+        return this.checkoutOptions;
+    }
+    async request(endpoint, options = {}, requestOptions = {}) {
+        if (!this.fetchImpl) {
+            throw new MoPayAPIError("fetch is not available in this runtime. Use Node.js 18+ or pass a fetch implementation.");
+        }
+        const controller = new AbortController();
+        const timeout = this.timeoutMs > 0
+            ? setTimeout(() => controller.abort(new Error("MoPay request timed out")), this.timeoutMs)
+            : undefined;
+        const signal = anySignal([controller.signal, requestOptions.signal].filter(Boolean));
+        const url = new URL(endpoint, this.baseUrl);
+        const requestInit = {
+            ...options,
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "User-Agent": this.userAgent,
+                ...options.headers,
+            },
+        };
+        if (signal) {
+            requestInit.signal = signal;
+        }
+        try {
+            const response = await this.fetchImpl(url, requestInit);
+            const data = await parseResponse(response);
+            const apiError = data;
+            if (!response.ok || apiError.success === false) {
+                throw new MoPayAPIError(apiError.error || apiError.message || "MoPay API request failed", {
+                    statusCode: response.status,
+                    code: apiError.code,
+                    response: data,
+                });
+            }
+            return data;
+        }
+        catch (error) {
+            if (error instanceof MoPayAPIError) {
+                throw error;
+            }
+            throw new MoPayAPIError(error instanceof Error ? error.message : "MoPay API request failed");
+        }
+        finally {
+            if (timeout !== undefined) {
+                clearTimeout(timeout);
+            }
+        }
+    }
+}
+function getNativeFetch() {
+    if (typeof globalThis.fetch !== "function") {
+        return undefined;
+    }
+    return globalThis.fetch.bind(globalThis);
+}
+async function parseResponse(response) {
+    const text = await response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { success: false, error: text };
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    const normalized = /^https?:\/\//i.test(baseUrl) ? baseUrl : `https://${baseUrl}`;
+    try {
+        const url = new URL(normalized);
+        return url.href.endsWith("/") ? url.href : `${url.href}/`;
+    }
+    catch {
+        throw new MoPayAPIError(`baseUrl must be a valid URL. Received: ${baseUrl}`);
+    }
+}
+function anySignal(signals) {
+    if (signals.length === 0) {
+        return undefined;
+    }
+    if (signals.length === 1) {
+        return signals[0];
+    }
+    const controller = new AbortController();
+    const abort = (event) => {
+        const signal = event.target;
+        controller.abort(signal.reason);
+    };
+    signals.forEach((signal) => {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+    });
+    return controller.signal;
+}

package/dist/checkout.d.ts

@@ -0,0 +1,6 @@
+import type { CheckoutHandle, CheckoutOptions, MoPayCheckoutOpenOptions } from "./types.js";
+export declare function checkout(paymentUrl: string, options?: CheckoutOptions): CheckoutHandle;
+export declare class MoPayCheckout {
+    static open(options: MoPayCheckoutOpenOptions): CheckoutHandle;
+}
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,eAAe,EACf,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAUpB,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAE1F;AAED,qBAAa,aAAa;IACxB,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc;CA6B/D"}