multi-payment-system 0.0.0-stage → 1.0.0

package/src/gateways/MidtransGateway.js

@@ -0,0 +1,123 @@
+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";
+
+/**
+ * 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 = Buffer.from(`${serverKey}:`).toString("base64");
+    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);
+  }
+}

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,119 @@
+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"],
+        xenditPaymentMethods: xenditMethods,
+        amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+        raw: data,
+      };
+    } catch (err) {
+      // If filtered methods are wrong for this business, retry with all activated channels
+      if (
+        xenditMethods.length &&
+        err.response?.data?.error_code === "UNAVAILABLE_PAYMENT_METHOD_ERROR"
+      ) {
+        delete payload.payment_methods;
+        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"],
+            xenditPaymentMethods: [],
+            warning:
+              `Requested channels ${xenditMethods.join(",")} unavailable on this Xendit business; invoice opened with all activated methods.`,
+            amountDisplay: formatMajor(ctx.amountMinor, ctx.currency),
+            raw: data,
+          };
+        } catch (retryErr) {
+          throw this.wrap(retryErr);
+        }
+      }
+      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"],
+  };
+}