multi-payment-system 0.0.0-stage → 1.1.0

package/src/client/PaymentClient.js

@@ -0,0 +1,173 @@
+import { requestJson, ClientHttpError } from "./http.js";
+
+/**
+ * Browser / React-safe client.
+ * Talks to YOUR payment backend (this package's Express server or any compatible API).
+ * Secret gateway keys stay on the server — do not put them in React.
+ *
+ * @example
+ * import { PaymentClient } from "multi-payment-system/client";
+ *
+ * const client = new PaymentClient({
+ *   baseUrl: "http://localhost:3000",
+ *   // apiKey: "optional-if-server-has-API_KEY",
+ * });
+ *
+ * const { payment } = await client.charge({
+ *   gateway: "xendit",
+ *   amount: 30,
+ *   currency: "SGD",
+ *   paymentMethod: "card",
+ *   keys: { secretKey: "..." }, // only if your backend accepts keys per request
+ *   returnUrl: window.location.origin + "/success",
+ * });
+ *
+ * client.openCheckout(payment);
+ */
+export class PaymentClient {
+  constructor({ baseUrl, apiKey, headers } = {}) {
+    if (!baseUrl) throw new Error("PaymentClient: baseUrl is required");
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey || "";
+    this.headers = headers || {};
+  }
+
+  #opts(extra = {}) {
+    return {
+      apiKey: this.apiKey,
+      headers: this.headers,
+      ...extra,
+    };
+  }
+
+  /** GET /api/payments/meta */
+  async meta() {
+    return requestJson(this.baseUrl, "/api/payments/meta", this.#opts());
+  }
+
+  /**
+   * POST /api/payments/charge
+   * Body can include gateway, amount, currency, paymentMethod, keys, returnUrl, ...
+   */
+  async charge(body) {
+    return requestJson(this.baseUrl, "/api/payments/charge", {
+      ...this.#opts(),
+      method: "POST",
+      body,
+    });
+  }
+
+  /** GET /api/payments/:id */
+  async getPayment(id) {
+    return requestJson(this.baseUrl, `/api/payments/${encodeURIComponent(id)}`, this.#opts());
+  }
+
+  /** POST /api/payments/:id/refresh */
+  async refresh(id, keys) {
+    return requestJson(this.baseUrl, `/api/payments/${encodeURIComponent(id)}/refresh`, {
+      ...this.#opts(),
+      method: "POST",
+      body: keys ? { keys } : {},
+    });
+  }
+
+  /** Yokke EDC: create attempt */
+  async createEdcAttempt(body) {
+    return requestJson(this.baseUrl, "/api/payments/attempts", {
+      ...this.#opts(),
+      method: "POST",
+      body,
+    });
+  }
+
+  /** Yokke EDC: report terminal result */
+  async reportTerminalResult(id, body) {
+    return requestJson(
+      this.baseUrl,
+      `/api/payments/attempts/${encodeURIComponent(id)}/terminal-result`,
+      {
+        ...this.#opts(),
+        method: "POST",
+        body,
+      }
+    );
+  }
+
+  /**
+   * Open hosted checkout in the current window, new tab, or return the URL.
+   * Supports Xendit/Stripe/Omise checkoutUrl and Midtrans redirect_url.
+   */
+  openCheckout(paymentOrUrl, { target = "_self" } = {}) {
+    const url =
+      typeof paymentOrUrl === "string"
+        ? paymentOrUrl
+        : paymentOrUrl?.checkoutUrl ||
+          paymentOrUrl?.payment?.checkoutUrl ||
+          paymentOrUrl?.qrImageUrl ||
+          paymentOrUrl?.payment?.qrImageUrl;
+
+    if (!url) {
+      throw new Error("No checkoutUrl on payment result");
+    }
+
+    if (typeof window === "undefined") {
+      return url;
+    }
+
+    if (target === "_blank") {
+      window.open(url, "_blank", "noopener,noreferrer");
+    } else {
+      window.location.assign(url);
+    }
+    return url;
+  }
+
+  /** Razorpay Checkout helper — loads Razorpay.js and opens modal (browser only). */
+  async openRazorpayCheckout(payment, options = {}) {
+    const checkout = payment?.checkout || payment?.payment?.checkout;
+    if (!checkout?.keyId || !checkout?.orderId) {
+      throw new Error("Razorpay checkout payload missing (keyId / orderId)");
+    }
+
+    await loadScript("https://checkout.razorpay.com/v1/checkout.js");
+    if (typeof window === "undefined" || !window.Razorpay) {
+      throw new Error("Razorpay SDK failed to load");
+    }
+
+    return new Promise((resolve, reject) => {
+      const rzp = new window.Razorpay({
+        key: checkout.keyId,
+        amount: checkout.amount,
+        currency: checkout.currency,
+        name: checkout.name || "Payment",
+        order_id: checkout.orderId,
+        prefill: checkout.prefill || {},
+        handler: (response) => resolve(response),
+        modal: {
+          ondismiss: () => reject(new Error("Razorpay checkout dismissed")),
+        },
+        ...options,
+      });
+      rzp.open();
+    });
+  }
+}
+
+function loadScript(src) {
+  if (typeof document === "undefined") {
+    return Promise.reject(new Error("document not available"));
+  }
+  const existing = document.querySelector(`script[src="${src}"]`);
+  if (existing) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    const s = document.createElement("script");
+    s.src = src;
+    s.async = true;
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error(`Failed to load ${src}`));
+    document.head.appendChild(s);
+  });
+}
+
+export { ClientHttpError };

package/src/client/http.js

@@ -0,0 +1,39 @@
+export class ClientHttpError extends Error {
+  constructor(message, status, details) {
+    super(message);
+    this.name = "ClientHttpError";
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export async function requestJson(baseUrl, path, { method = "GET", body, apiKey, headers } = {}) {
+  const url = `${String(baseUrl).replace(/\/$/, "")}${path}`;
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Accept: "application/json",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+      ...(apiKey ? { "x-api-key": apiKey } : {}),
+      ...(headers || {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    json = null;
+  }
+
+  if (!res.ok) {
+    throw new ClientHttpError(
+      json?.error || `Request failed (${res.status})`,
+      res.status,
+      json?.details || json
+    );
+  }
+
+  return json;
+}

package/src/client/index.js

@@ -0,0 +1,35 @@
+/**
+ * Browser / React entry — no Express.
+ *
+ * @example
+ * import { PaymentClient, redirectToCheckout } from "multi-payment-system/client";
+ */
+export { PaymentClient, ClientHttpError } from "./PaymentClient.js";
+export { requestJson } from "./http.js";
+
+export {
+  listGateways,
+  GATEWAY_NAMES,
+  gatewayRegionsHint,
+  SUPPORTED_CURRENCIES,
+} from "../meta.js";
+
+export {
+  toMinorUnits,
+  toMajorUnits,
+  formatMajor,
+  normalizeCurrency,
+} from "../utils/money.js";
+
+export {
+  normalizeMethods,
+  mapMethodsForGateway,
+  PAYMENT_METHOD_HINTS,
+} from "../utils/paymentMethods.js";
+
+import { PaymentClient } from "./PaymentClient.js";
+
+/** Open hosted checkout URL (Xendit / Stripe / Omise / Midtrans). */
+export function redirectToCheckout(paymentOrUrl, options) {
+  return new PaymentClient({ baseUrl: "https://local" }).openCheckout(paymentOrUrl, options);
+}

package/src/client/react.js

@@ -0,0 +1,107 @@
+/**
+ * React helpers. Peer-depends on react.
+ *
+ * @example
+ * import { usePaymentClient } from "multi-payment-system/react";
+ *
+ * function PayButton() {
+ *   const { chargeAndRedirect, loading, error } = usePaymentClient({
+ *     baseUrl: import.meta.env.VITE_PAY_API,
+ *   });
+ *
+ *   return (
+ *     <button
+ *       disabled={loading}
+ *       onClick={() =>
+ *         chargeAndRedirect({
+ *           gateway: "xendit",
+ *           amount: 30,
+ *           currency: "SGD",
+ *           paymentMethod: "card",
+ *           keys: { secretKey: "..." }, // better: store keys only on server
+ *           returnUrl: window.location.origin + "/success",
+ *         })
+ *       }
+ *     >
+ *       {loading ? "Opening…" : "Pay"}
+ *     </button>
+ *   );
+ * }
+ */
+import { useCallback, useMemo, useState } from "react";
+import { PaymentClient } from "./PaymentClient.js";
+
+export function usePaymentClient({ baseUrl, apiKey, headers } = {}) {
+  const client = useMemo(
+    () => new PaymentClient({ baseUrl, apiKey, headers }),
+    [baseUrl, apiKey, headers]
+  );
+
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [payment, setPayment] = useState(null);
+
+  const charge = useCallback(
+    async (body) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const res = await client.charge(body);
+        setPayment(res.payment || res);
+        return res;
+      } catch (err) {
+        setError(err);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client]
+  );
+
+  const chargeAndRedirect = useCallback(
+    async (body, openOptions) => {
+      const res = await charge(body);
+      const pay = res.payment || res;
+      if (pay?.checkout) {
+        await client.openRazorpayCheckout(pay, openOptions);
+      } else {
+        client.openCheckout(pay, openOptions);
+      }
+      return res;
+    },
+    [charge, client]
+  );
+
+  const refresh = useCallback(
+    async (id, keys) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const res = await client.refresh(id, keys);
+        setPayment(res.payment || res);
+        return res;
+      } catch (err) {
+        setError(err);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client]
+  );
+
+  return {
+    client,
+    loading,
+    error,
+    payment,
+    charge,
+    chargeAndRedirect,
+    refresh,
+    openCheckout: (p, opts) => client.openCheckout(p, opts),
+    openRazorpayCheckout: (p, opts) => client.openRazorpayCheckout(p, opts),
+  };
+}
+
+export { PaymentClient } from "./PaymentClient.js";

package/src/config.js

@@ -0,0 +1,10 @@
+import dotenv from "dotenv";
+
+dotenv.config();
+
+export const config = {
+  port: Number(process.env.PORT || 3000),
+  nodeEnv: process.env.NODE_ENV || "development",
+  apiKey: process.env.API_KEY || "",
+  publicBaseUrl: process.env.PUBLIC_BASE_URL || "",
+};

package/src/gateways/BaseGateway.js

@@ -0,0 +1,41 @@
+export class BaseGateway {
+  constructor(name) {
+    this.name = name;
+  }
+
+  /**
+   * @param {object} ctx
+   * @param {string} ctx.paymentId
+   * @param {number} ctx.amountMinor
+   * @param {string} ctx.currency
+   * @param {object} ctx.keys
+   * @param {string} [ctx.orderId]
+   * @param {string} [ctx.description]
+   * @param {object} [ctx.customer]
+   * @param {string} [ctx.returnUrl]
+   * @param {string} [ctx.cancelUrl]
+   * @param {object} [ctx.metadata]
+   * @param {string} [ctx.paymentMethod]
+   */
+  async createPayment(_ctx) {
+    throw new Error(`${this.name}: createPayment not implemented`);
+  }
+
+  async getStatus(_ctx) {
+    throw new Error(`${this.name}: getStatus not implemented`);
+  }
+
+  normalizeStatus(raw) {
+    const s = String(raw || "").toLowerCase();
+    if (["succeeded", "success", "paid", "capture", "captured", "settlement", "completed"].includes(s)) {
+      return "succeeded";
+    }
+    if (["pending", "requires_action", "requires_payment_method", "awaiting_payment", "created", "authorized"].includes(s)) {
+      return "pending";
+    }
+    if (["failed", "failure", "cancel", "cancelled", "canceled", "expired", "deny", "denied", "void"].includes(s)) {
+      return "failed";
+    }
+    return "pending";
+  }
+}

package/src/gateways/MidtransGateway.js

@@ -0,0 +1,124 @@
+import axios from "axios";
+import { BaseGateway } from "./BaseGateway.js";
+import { toMajorUnits, formatMajor } from "../utils/money.js";
+import { AppError } from "../utils/errors.js";
+import { normalizeMethods, mapMethodsForGateway } from "../utils/paymentMethods.js";
+import { toBase64 } from "../utils/base64.js";
+
+/**
+ * Midtrans — Indonesia-focused (Snap + Core API).
+ * paymentMethod examples: card | qr | ewallet | bank | gopay | shopeepay
+ */
+export class MidtransGateway extends BaseGateway {
+  constructor() {
+    super("midtrans");
+  }
+
+  baseUrl(isProduction) {
+    return isProduction
+      ? "https://app.midtrans.com"
+      : "https://app.sandbox.midtrans.com";
+  }
+
+  apiBase(isProduction) {
+    return isProduction
+      ? "https://api.midtrans.com"
+      : "https://api.sandbox.midtrans.com";
+  }
+
+  authHeader(serverKey) {
+    const token = toBase64(`${serverKey}:`);
+    return { Authorization: `Basic ${token}`, "Content-Type": "application/json" };
+  }
+
+  async createPayment(ctx) {
+    const serverKey = ctx.keys.serverKey || ctx.keys.secretKey;
+    if (!serverKey) throw new AppError("Midtrans keys.serverKey (or secretKey) is required");
+
+    const isProduction = Boolean(ctx.keys.isProduction);
+    const orderId = ctx.orderId || ctx.paymentId;
+    const grossAmount = Math.round(toMajorUnits(ctx.amountMinor, ctx.currency));
+    const methods = normalizeMethods(ctx.paymentMethod, ctx.paymentMethods);
+    const enabled = mapMethodsForGateway("midtrans", methods, ctx.currency);
+
+    const payload = {
+      transaction_details: {
+        order_id: orderId,
+        gross_amount: grossAmount,
+      },
+      item_details: [
+        {
+          id: orderId,
+          price: grossAmount,
+          quantity: 1,
+          name: (ctx.description || "Kiosk payment").slice(0, 50),
+        },
+      ],
+      customer_details: {
+        first_name: ctx.customer?.name || "Customer",
+        email: ctx.customer?.email || undefined,
+        phone: ctx.customer?.phone || undefined,
+      },
+      callbacks: {
+        finish: ctx.returnUrl || undefined,
+        error: ctx.cancelUrl || ctx.returnUrl || undefined,
+      },
+      custom_field1: ctx.paymentId,
+      metadata: ctx.metadata || {},
+    };
+
+    if (enabled.length) {
+      payload.enabled_payments = enabled;
+    }
+
+    try {
+      const { data } = await axios.post(
+        `${this.baseUrl(isProduction)}/snap/v1/transactions`,
+        payload,
+        { headers: this.authHeader(serverKey), timeout: 30000 }
+      );
+
+      return {
+        status: "pending",
+        gatewayRef: orderId,
+        checkoutUrl: data.redirect_url,
+        token: data.token,
+        paymentMethods: methods.length ? methods : ["all"],
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  async getStatus(ctx) {
+    const serverKey = ctx.keys.serverKey || ctx.keys.secretKey;
+    if (!serverKey) throw new AppError("Midtrans keys.serverKey (or secretKey) is required");
+    const isProduction = Boolean(ctx.keys.isProduction);
+    const orderId = ctx.gatewayRef || ctx.orderId;
+
+    try {
+      const { data } = await axios.get(
+        `${this.apiBase(isProduction)}/v2/${encodeURIComponent(orderId)}/status`,
+        { headers: this.authHeader(serverKey), timeout: 30000 }
+      );
+      return {
+        status: this.normalizeStatus(data.transaction_status || data.status_code),
+        gatewayRef: data.order_id || orderId,
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  wrap(err) {
+    const msg =
+      err.response?.data?.error_messages?.[0] ||
+      err.response?.data?.status_message ||
+      err.message ||
+      "Midtrans error";
+    return new AppError(String(msg), err.response?.status || 502, err.response?.data);
+  }
+}

package/src/gateways/OmiseGateway.js

@@ -0,0 +1,137 @@
+import axios from "axios";
+import { BaseGateway } from "./BaseGateway.js";
+import { formatMajor } from "../utils/money.js";
+import { AppError } from "../utils/errors.js";
+import { normalizeMethods, mapMethodsForGateway } from "../utils/paymentMethods.js";
+
+/**
+ * Omise (Opn) — Thailand, Singapore, Japan, Malaysia.
+ * paymentMethod examples: card | qr | paynow | promptpay | fpx
+ *
+ * Note: card usually needs a client-side token (tokn_...); for kiosk QR use paynow/promptpay.
+ */
+export class OmiseGateway extends BaseGateway {
+  constructor() {
+    super("omise");
+  }
+
+  client(secretKey) {
+    if (!secretKey) throw new AppError("Omise keys.secretKey is required");
+    return axios.create({
+      baseURL: "https://api.omise.co",
+      auth: { username: secretKey, password: "" },
+      headers: { "Content-Type": "application/json" },
+      timeout: 30000,
+    });
+  }
+
+  resolveSourceType(ctx, methods) {
+    const mapped = mapMethodsForGateway("omise", methods, ctx.currency);
+    if (mapped.length) return mapped[0];
+
+    if (ctx.keys.sourceType) return ctx.keys.sourceType;
+
+    return (
+      {
+        SGD: "paynow",
+        MYR: "fpx",
+        THB: "promptpay",
+      }[ctx.currency] || "promptpay"
+    );
+  }
+
+  async createPayment(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    const returnUri = ctx.returnUrl || ctx.keys.returnUri;
+    const methods = normalizeMethods(ctx.paymentMethod, ctx.paymentMethods);
+    const sourceType = this.resolveSourceType(ctx, methods);
+
+    if (sourceType === "card" && !ctx.keys.cardToken && !ctx.cardToken) {
+      throw new AppError(
+        "Omise card payments need keys.cardToken (from Om.js). For kiosk QR use paymentMethod: \"qr\" or \"paynow\" / \"promptpay\".",
+        400
+      );
+    }
+
+    try {
+      let sourceId = ctx.keys.cardToken || ctx.cardToken || null;
+      let source = null;
+
+      if (!sourceId) {
+        const sourcePayload = {
+          amount: ctx.amountMinor,
+          currency: ctx.currency.toLowerCase(),
+          type: sourceType,
+        };
+        if (returnUri) sourcePayload.return_uri = returnUri;
+        if (sourceType === "fpx" && (ctx.keys.bank || ctx.bank)) {
+          sourcePayload.bank = ctx.keys.bank || ctx.bank;
+        }
+
+        const created = await api.post("/sources", sourcePayload);
+        source = created.data;
+        sourceId = source.id;
+      }
+
+      const chargePayload = {
+        amount: ctx.amountMinor,
+        currency: ctx.currency.toLowerCase(),
+        source: sourceId,
+        description: ctx.description || `Payment ${ctx.paymentId}`,
+        metadata: {
+          paymentId: ctx.paymentId,
+          orderId: ctx.orderId || "",
+          paymentMethod: methods.join(",") || sourceType,
+          ...(ctx.metadata || {}),
+        },
+      };
+      if (returnUri) chargePayload.return_uri = returnUri;
+
+      const { data: charge } = await api.post("/charges", chargePayload);
+
+      return {
+        status: this.normalizeStatus(
+          charge.status === "successful"
+            ? "succeeded"
+            : charge.status === "pending"
+              ? "pending"
+              : charge.status
+        ),
+        gatewayRef: charge.id,
+        checkoutUrl: charge.authorize_uri || source?.scannable_code?.image?.download_uri,
+        qrImageUrl: source?.scannable_code?.image?.download_uri,
+        paymentMethods: methods.length ? methods : [sourceType],
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: { source, charge },
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  async getStatus(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    try {
+      const { data } = await api.get(`/charges/${ctx.gatewayRef}`);
+      return {
+        status: this.normalizeStatus(
+          data.status === "successful" ? "succeeded" : data.status
+        ),
+        gatewayRef: data.id,
+        checkoutUrl: data.authorize_uri,
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  wrap(err) {
+    const msg =
+      err.response?.data?.message ||
+      err.response?.data?.error ||
+      err.message ||
+      "Omise error";
+    return new AppError(String(msg), err.response?.status || 502, err.response?.data);
+  }
+}