multi-payment-system 0.0.0-stage → 1.1.0

package/src/gateways/RazorpayGateway.js

@@ -0,0 +1,118 @@
+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";
+
+/**
+ * Razorpay — India + international.
+ * paymentMethod examples: card | qr | upi | ewallet | bank
+ */
+export class RazorpayGateway extends BaseGateway {
+  constructor() {
+    super("razorpay");
+  }
+
+  client(keys) {
+    const keyId = keys.keyId || keys.publicKey;
+    const keySecret = keys.keySecret || keys.secretKey;
+    if (!keyId || !keySecret) {
+      throw new AppError("Razorpay keys.keyId and keys.keySecret are required");
+    }
+    return axios.create({
+      baseURL: "https://api.razorpay.com/v1",
+      auth: { username: keyId, password: keySecret },
+      headers: { "Content-Type": "application/json" },
+      timeout: 30000,
+    });
+  }
+
+  async createPayment(ctx) {
+    const api = this.client(ctx.keys);
+    const methods = normalizeMethods(ctx.paymentMethod, ctx.paymentMethods);
+    const rzpMethods = mapMethodsForGateway("razorpay", methods, ctx.currency);
+
+    const payload = {
+      amount: ctx.amountMinor,
+      currency: ctx.currency,
+      receipt: (ctx.orderId || ctx.paymentId).slice(0, 40),
+      notes: {
+        paymentId: ctx.paymentId,
+        paymentMethod: methods.join(",") || undefined,
+        ...(ctx.metadata || {}),
+      },
+    };
+
+    // Prefer method for single channel (upi/card/netbanking/wallet)
+    if (rzpMethods.length === 1) {
+      payload.method = rzpMethods[0];
+    }
+
+    try {
+      const { data } = await api.post("/orders", payload);
+      const checkout = {
+        keyId: ctx.keys.keyId || ctx.keys.publicKey,
+        orderId: data.id,
+        amount: data.amount,
+        currency: data.currency,
+        name: ctx.description || "Kiosk Payment",
+        prefill: {
+          name: ctx.customer?.name,
+          email: ctx.customer?.email,
+          contact: ctx.customer?.phone,
+        },
+      };
+
+      if (rzpMethods.length === 1) {
+        checkout.method = rzpMethods[0];
+      } else if (rzpMethods.length > 1) {
+        checkout.config = {
+          display: {
+            blocks: {
+              banks: {
+                name: "Pay using",
+                instruments: rzpMethods.map((method) => ({ method })),
+              },
+            },
+            sequence: ["block.banks"],
+            preferences: { show_default_blocks: false },
+          },
+        };
+      }
+
+      return {
+        status: this.normalizeStatus(data.status === "created" ? "pending" : data.status),
+        gatewayRef: data.id,
+        checkout,
+        paymentMethods: methods.length ? methods : ["all"],
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  async getStatus(ctx) {
+    const api = this.client(ctx.keys);
+    try {
+      const { data } = await api.get(`/orders/${ctx.gatewayRef}`);
+      return {
+        status: this.normalizeStatus(data.status === "paid" ? "succeeded" : data.status),
+        gatewayRef: data.id,
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  wrap(err) {
+    const msg =
+      err.response?.data?.error?.description ||
+      err.response?.data?.error?.code ||
+      err.message ||
+      "Razorpay error";
+    return new AppError(String(msg), err.response?.status || 502, err.response?.data);
+  }
+}

package/src/gateways/StripeGateway.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";
+
+/**
+ * Stripe — global (SG, MY, etc.).
+ * paymentMethod examples: card | qr | paynow | fpx | grabpay | promptpay
+ */
+export class StripeGateway extends BaseGateway {
+  constructor() {
+    super("stripe");
+  }
+
+  client(secretKey) {
+    if (!secretKey) throw new AppError("Stripe keys.secretKey is required");
+    return axios.create({
+      baseURL: "https://api.stripe.com/v1",
+      headers: {
+        Authorization: `Bearer ${secretKey}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      timeout: 30000,
+    });
+  }
+
+  toForm(obj, prefix = "") {
+    const params = new URLSearchParams();
+    const walk = (value, path) => {
+      if (value === undefined || value === null) return;
+      if (typeof value === "object" && !Array.isArray(value)) {
+        for (const [k, v] of Object.entries(value)) {
+          walk(v, path ? `${path}[${k}]` : k);
+        }
+        return;
+      }
+      if (Array.isArray(value)) {
+        value.forEach((v, i) => walk(v, `${path}[${i}]`));
+        return;
+      }
+      params.append(path, String(value));
+    };
+    walk(obj, prefix);
+    return params;
+  }
+
+  async createPayment(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    const successUrl =
+      ctx.keys.successUrl ||
+      ctx.returnUrl ||
+      "https://example.com/success?session_id={CHECKOUT_SESSION_ID}";
+    const cancelUrl = ctx.keys.cancelUrl || ctx.cancelUrl || ctx.returnUrl || "https://example.com/cancel";
+
+    const methods = normalizeMethods(ctx.paymentMethod, ctx.paymentMethods);
+    let stripeMethods = mapMethodsForGateway("stripe", methods, ctx.currency);
+
+    // Sensible defaults by currency when only "qr" was requested
+    if (methods.includes("qr") && ctx.currency === "SGD") stripeMethods = ["paynow"];
+    if (methods.includes("qr") && ctx.currency === "THB") stripeMethods = ["promptpay"];
+
+    const session = {
+      mode: "payment",
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+      client_reference_id: ctx.orderId || ctx.paymentId,
+      line_items: [
+        {
+          quantity: 1,
+          price_data: {
+            currency: ctx.currency.toLowerCase(),
+            unit_amount: ctx.amountMinor,
+            product_data: {
+              name: (ctx.description || "Kiosk payment").slice(0, 120),
+            },
+          },
+        },
+      ],
+      metadata: {
+        paymentId: ctx.paymentId,
+        orderId: ctx.orderId || "",
+        paymentMethod: methods.join(",") || "",
+        ...(ctx.metadata || {}),
+      },
+    };
+
+    if (stripeMethods.length) {
+      session.payment_method_types = stripeMethods;
+    }
+
+    const body = this.toForm(session);
+
+    if (ctx.customer?.email) {
+      body.append("customer_email", ctx.customer.email);
+    }
+
+    try {
+      const { data } = await api.post("/checkout/sessions", body);
+      return {
+        status: this.normalizeStatus(data.payment_status === "paid" ? "succeeded" : "pending"),
+        gatewayRef: data.id,
+        checkoutUrl: data.url,
+        clientSecret: data.client_secret || undefined,
+        paymentMethods: methods.length ? methods : ["all"],
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  async getStatus(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    try {
+      const { data } = await api.get(`/checkout/sessions/${ctx.gatewayRef}`);
+      const paid = data.payment_status === "paid" || data.status === "complete";
+      return {
+        status: paid ? "succeeded" : this.normalizeStatus(data.status),
+        gatewayRef: data.id,
+        checkoutUrl: data.url,
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  wrap(err) {
+    const msg =
+      err.response?.data?.error?.message ||
+      err.message ||
+      "Stripe error";
+    return new AppError(String(msg), err.response?.status || 502, err.response?.data);
+  }
+}

package/src/gateways/XenditGateway.js

@@ -0,0 +1,95 @@
+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";
+
+/**
+ * Xendit — strong in ID, PH, MY, TH, VN, SG.
+ * paymentMethod examples: card | qr | ewallet | bank | paynow | ovo | dana
+ */
+export class XenditGateway extends BaseGateway {
+  constructor() {
+    super("xendit");
+  }
+
+  client(secretKey) {
+    if (!secretKey) throw new AppError("Xendit keys.secretKey is required");
+    return axios.create({
+      baseURL: "https://api.xendit.co",
+      auth: { username: secretKey, password: "" },
+      headers: { "Content-Type": "application/json" },
+      timeout: 30000,
+    });
+  }
+
+  async createPayment(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    const amount = toMajorUnits(ctx.amountMinor, ctx.currency);
+    const externalId = ctx.orderId || ctx.paymentId;
+    const methods = normalizeMethods(ctx.paymentMethod, ctx.paymentMethods);
+    const xenditMethods = mapMethodsForGateway("xendit", methods, ctx.currency);
+
+    const payload = {
+      external_id: externalId,
+      amount,
+      currency: ctx.currency,
+      description: ctx.description || `Payment ${externalId}`,
+      invoice_duration: 3600,
+      success_redirect_url: ctx.returnUrl || undefined,
+      failure_redirect_url: ctx.cancelUrl || ctx.returnUrl || undefined,
+      metadata: {
+        paymentId: ctx.paymentId,
+        paymentMethod: methods.join(",") || undefined,
+        ...(ctx.metadata || {}),
+      },
+    };
+
+    // Restrict invoice payment channels when client asks for card/qr/etc.
+    if (xenditMethods.length) {
+      payload.payment_methods = xenditMethods;
+    }
+
+    if (ctx.customer?.email) {
+      payload.payer_email = ctx.customer.email;
+    }
+
+    try {
+      const { data } = await api.post("/v2/invoices", payload);
+      return {
+        status: this.normalizeStatus(data.status),
+        gatewayRef: data.id,
+        checkoutUrl: data.invoice_url,
+        paymentMethods: methods.length ? methods : ["all"],
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  async getStatus(ctx) {
+    const api = this.client(ctx.keys.secretKey);
+    try {
+      const { data } = await api.get(`/v2/invoices/${ctx.gatewayRef}`);
+      return {
+        status: this.normalizeStatus(data.status),
+        gatewayRef: data.id,
+        checkoutUrl: data.invoice_url,
+        raw: data,
+      };
+    } catch (err) {
+      throw this.wrap(err);
+    }
+  }
+
+  wrap(err) {
+    const msg =
+      err.response?.data?.message ||
+      err.response?.data?.error_code ||
+      err.message ||
+      "Xendit error";
+    return new AppError(String(msg), err.response?.status || 502, err.response?.data);
+  }
+}

package/src/gateways/index.js

@@ -0,0 +1,42 @@
+import { XenditGateway } from "./XenditGateway.js";
+import { MidtransGateway } from "./MidtransGateway.js";
+import { RazorpayGateway } from "./RazorpayGateway.js";
+import { StripeGateway } from "./StripeGateway.js";
+import { OmiseGateway } from "./OmiseGateway.js";
+import { AppError } from "../utils/errors.js";
+
+const gateways = {
+  xendit: new XenditGateway(),
+  midtrans: new MidtransGateway(),
+  razorpay: new RazorpayGateway(),
+  // common typos
+  razerpay: new RazorpayGateway(),
+  stripe: new StripeGateway(),
+  // common typo from request
+  stipt: new StripeGateway(),
+  omise: new OmiseGateway(),
+};
+
+export const GATEWAY_NAMES = ["xendit", "midtrans", "razorpay", "stripe", "omise"];
+
+export function getGateway(name) {
+  const key = String(name || "").trim().toLowerCase();
+  const gw = gateways[key];
+  if (!gw) {
+    throw new AppError(
+      `Unsupported gateway "${name}". Use one of: ${GATEWAY_NAMES.join(", ")}`,
+      400
+    );
+  }
+  return gw;
+}
+
+export function gatewayRegionsHint() {
+  return {
+    xendit: ["SG", "MY", "ID", "PH", "TH", "VN"],
+    midtrans: ["ID"],
+    razorpay: ["IN", "international"],
+    stripe: ["SG", "MY", "global"],
+    omise: ["SG", "MY", "TH", "JP"],
+  };
+}

package/src/index.js

@@ -0,0 +1,48 @@
+/**
+ * multi-payment-system — Node / server SDK
+ *
+ * For React / browser use:
+ *   import { PaymentClient } from "multi-payment-system/client";
+ *   import { usePaymentClient } from "multi-payment-system/react";
+ *
+ * @example
+ * import { XenditGateway, charge } from "multi-payment-system";
+ */
+
+export { BaseGateway } from "./gateways/BaseGateway.js";
+export { XenditGateway } from "./gateways/XenditGateway.js";
+export { MidtransGateway } from "./gateways/MidtransGateway.js";
+export { RazorpayGateway } from "./gateways/RazorpayGateway.js";
+export { StripeGateway } from "./gateways/StripeGateway.js";
+export { OmiseGateway } from "./gateways/OmiseGateway.js";
+
+export {
+  getGateway,
+  GATEWAY_NAMES,
+  gatewayRegionsHint,
+} from "./gateways/index.js";
+
+export { charge, getStatus, listGateways } from "./api.js";
+
+export { PaymentService, paymentService } from "./services/PaymentService.js";
+
+export {
+  toMinorUnits,
+  toMajorUnits,
+  formatMajor,
+  normalizeCurrency,
+  SUPPORTED_CURRENCIES,
+} from "./utils/money.js";
+
+export {
+  normalizeMethods,
+  mapMethodsForGateway,
+  PAYMENT_METHOD_HINTS,
+} from "./utils/paymentMethods.js";
+
+export { AppError } from "./utils/errors.js";
+
+export { createApp } from "./app.js";
+
+// Re-export browser client for convenience (still prefer /client in React apps)
+export { PaymentClient, redirectToCheckout } from "./client/index.js";

package/src/meta.js

@@ -0,0 +1,35 @@
+/** Lightweight meta — safe for browser bundles (no gateway class imports). */
+
+export const GATEWAY_NAMES = ["xendit", "midtrans", "razorpay", "stripe", "omise"];
+
+export function gatewayRegionsHint() {
+  return {
+    xendit: ["SG", "MY", "ID", "PH", "TH", "VN"],
+    midtrans: ["ID"],
+    razorpay: ["IN", "international"],
+    stripe: ["SG", "MY", "global"],
+    omise: ["SG", "MY", "TH", "JP"],
+  };
+}
+
+export const SUPPORTED_CURRENCIES = [
+  "SGD",
+  "MYR",
+  "IDR",
+  "THB",
+  "PHP",
+  "VND",
+  "USD",
+  "INR",
+  "JPY",
+  "AUD",
+  "HKD",
+];
+
+export function listGateways() {
+  return {
+    gateways: GATEWAY_NAMES,
+    regions: gatewayRegionsHint(),
+    currencies: SUPPORTED_CURRENCIES,
+  };
+}

package/src/middleware/auth.js

@@ -0,0 +1,11 @@
+import { config } from "../config.js";
+import { AppError } from "../utils/errors.js";
+
+export function optionalApiKey(req, _res, next) {
+  if (!config.apiKey) return next();
+  const header = req.header("x-api-key") || req.header("authorization")?.replace(/^Bearer\s+/i, "");
+  if (header !== config.apiKey) {
+    return next(new AppError("Unauthorized", 401));
+  }
+  return next();
+}

package/src/routes/payments.js

@@ -0,0 +1,156 @@
+import { Router } from "express";
+import { z } from "zod";
+import { paymentService } from "../services/PaymentService.js";
+import { GATEWAY_NAMES, gatewayRegionsHint } from "../gateways/index.js";
+import { SUPPORTED_CURRENCIES } from "../utils/money.js";
+import { PAYMENT_METHOD_HINTS } from "../utils/paymentMethods.js";
+import { AppError } from "../utils/errors.js";
+
+const router = Router();
+
+const chargeSchema = z.object({
+  gateway: z.string().min(1),
+  amount: z.number().positive(),
+  currency: z.string().min(3).max(3),
+  keys: z.record(z.any()),
+  orderId: z.string().optional(),
+  description: z.string().optional(),
+  customer: z
+    .object({
+      name: z.string().optional(),
+      email: z.string().email().optional(),
+      phone: z.string().optional(),
+    })
+    .optional(),
+  returnUrl: z.string().url().optional(),
+  cancelUrl: z.string().url().optional(),
+  // card | qr | ewallet | bank | paynow | promptpay | fpx | upi | gopay | ...
+  paymentMethod: z.string().optional(),
+  // e.g. ["card", "qr"] to allow multiple channels
+  paymentMethods: z.union([z.array(z.string()), z.string()]).optional(),
+  cardToken: z.string().optional(),
+  bank: z.string().optional(),
+  amountAlreadyMinor: z.boolean().optional(),
+  metadata: z.record(z.any()).optional(),
+});
+
+const edcSchema = z.object({
+  amount: z.number().positive(),
+  currency: z.string().min(3).max(3).default("IDR"),
+  orderId: z.string().optional(),
+  deviceId: z.string().optional(),
+  storeId: z.string().optional(),
+  amountAlreadyMinor: z.boolean().optional(),
+  metadata: z.record(z.any()).optional(),
+});
+
+const terminalResultSchema = z.object({
+  status: z.string().min(1),
+  approvalCode: z.string().optional(),
+  referenceNo: z.string().optional(),
+  rrn: z.string().optional(),
+  cardBrand: z.string().optional(),
+  maskedPan: z.string().optional(),
+  amountMinor: z.number().optional(),
+  raw: z.any().optional(),
+});
+
+router.get("/meta", (_req, res) => {
+  res.json({
+    ok: true,
+    gateways: GATEWAY_NAMES,
+    regions: gatewayRegionsHint(),
+    currencies: SUPPORTED_CURRENCIES,
+    paymentMethods: PAYMENT_METHOD_HINTS,
+    note: "Pass gateway, keys, amount, currency, and optional paymentMethod/paymentMethods (card, qr, ewallet, bank, ...).",
+  });
+});
+
+/** Create online payment via selected gateway */
+router.post("/charge", async (req, res, next) => {
+  try {
+    const parsed = chargeSchema.safeParse(req.body);
+    if (!parsed.success) {
+      throw new AppError("Invalid request body", 400, parsed.error.flatten());
+    }
+    const payment = await paymentService.createOnlinePayment(parsed.data);
+    res.status(201).json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+/** Alias matching the integration guide naming */
+router.post("/attempts", async (req, res, next) => {
+  try {
+    // If gateway is provided → online; otherwise treat as EDC attempt
+    if (req.body?.gateway) {
+      const parsed = chargeSchema.safeParse(req.body);
+      if (!parsed.success) {
+        throw new AppError("Invalid request body", 400, parsed.error.flatten());
+      }
+      const payment = await paymentService.createOnlinePayment(parsed.data);
+      return res.status(201).json({ ok: true, payment });
+    }
+
+    const parsed = edcSchema.safeParse(req.body);
+    if (!parsed.success) {
+      throw new AppError("Invalid request body", 400, parsed.error.flatten());
+    }
+    const payment = paymentService.createEdcAttempt(parsed.data);
+    return res.status(201).json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+router.post("/attempts/:id/terminal-result", (req, res, next) => {
+  try {
+    const parsed = terminalResultSchema.safeParse(req.body);
+    if (!parsed.success) {
+      throw new AppError("Invalid request body", 400, parsed.error.flatten());
+    }
+    const payment = paymentService.recordTerminalResult(req.params.id, parsed.data);
+    res.json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+router.get("/", (_req, res) => {
+  res.json({ ok: true, payments: paymentService.listPayments() });
+});
+
+router.get("/:id", (req, res, next) => {
+  try {
+    const payment = paymentService.getPayment(req.params.id);
+    res.json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+router.post("/:id/refresh", async (req, res, next) => {
+  try {
+    const payment = await paymentService.refreshStatus(req.params.id, req.body?.keys);
+    res.json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+router.post("/:id/reconcile", async (req, res, next) => {
+  try {
+    // Same as refresh for online; for EDC just returns current state
+    const existing = paymentService.getPayment(req.params.id);
+    if (existing.type === "edc") {
+      return res.json({ ok: true, payment: existing, note: "EDC reconcile is manual via terminal-result / last-txn inquiry on device" });
+    }
+    const payment = await paymentService.refreshStatus(req.params.id, req.body?.keys);
+    return res.json({ ok: true, payment });
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;