multi-payment-system 0.0.0-stage → 1.1.0

package/src/routes/webhooks.js

@@ -0,0 +1,91 @@
+import { Router } from "express";
+import { paymentService } from "../services/PaymentService.js";
+
+const router = Router();
+
+function mapXendit(body) {
+  const statusMap = {
+    PAID: "succeeded",
+    SETTLED: "succeeded",
+    EXPIRED: "failed",
+    PENDING: "pending",
+  };
+  return {
+    gatewayRef: body.id || body.invoice_id,
+    status: statusMap[String(body.status || "").toUpperCase()] || "pending",
+  };
+}
+
+function mapMidtrans(body) {
+  const s = String(body.transaction_status || "").toLowerCase();
+  let status = "pending";
+  if (["capture", "settlement"].includes(s)) status = "succeeded";
+  if (["deny", "cancel", "expire", "failure"].includes(s)) status = "failed";
+  return {
+    gatewayRef: body.order_id,
+    status,
+  };
+}
+
+function mapRazorpay(body) {
+  const event = body.event || "";
+  const entity = body.payload?.payment?.entity || body.payload?.order?.entity || {};
+  let status = "pending";
+  if (event.includes("captured") || entity.status === "captured" || entity.status === "paid") {
+    status = "succeeded";
+  }
+  if (event.includes("failed") || entity.status === "failed") status = "failed";
+  return {
+    gatewayRef: entity.order_id || entity.id,
+    status,
+  };
+}
+
+function mapStripe(body) {
+  const type = body.type || "";
+  const obj = body.data?.object || {};
+  let status = "pending";
+  if (type === "checkout.session.completed" && obj.payment_status === "paid") {
+    status = "succeeded";
+  }
+  if (type.includes("payment_intent.payment_failed")) status = "failed";
+  return {
+    gatewayRef: obj.id,
+    status,
+  };
+}
+
+function mapOmise(body) {
+  const data = body.data || body;
+  let status = "pending";
+  if (data.status === "successful") status = "succeeded";
+  if (data.status === "failed" || data.status === "expired") status = "failed";
+  return {
+    gatewayRef: data.id,
+    status,
+  };
+}
+
+async function handle(gateway, mapper, req, res) {
+  const mapped = mapper(req.body || {});
+  const updated = paymentService.applyWebhookUpdate({
+    gateway,
+    gatewayRef: mapped.gatewayRef,
+    status: mapped.status,
+    raw: req.body,
+  });
+  res.json({
+    ok: true,
+    matched: Boolean(updated),
+    paymentId: updated?.id || null,
+    status: updated?.status || mapped.status,
+  });
+}
+
+router.post("/xendit", (req, res) => handle("xendit", mapXendit, req, res));
+router.post("/midtrans", (req, res) => handle("midtrans", mapMidtrans, req, res));
+router.post("/razorpay", (req, res) => handle("razorpay", mapRazorpay, req, res));
+router.post("/stripe", (req, res) => handle("stripe", mapStripe, req, res));
+router.post("/omise", (req, res) => handle("omise", mapOmise, req, res));
+
+export default router;

package/src/server.js

@@ -0,0 +1,11 @@
+import { createApp } from "./app.js";
+import { config } from "./config.js";
+
+const app = createApp();
+
+app.listen(config.port, () => {
+  console.log(`Payment server listening on http://localhost:${config.port}`);
+  console.log(`Health:  GET  http://localhost:${config.port}/health`);
+  console.log(`Charge:  POST http://localhost:${config.port}/api/payments/charge`);
+  console.log(`Meta:    GET  http://localhost:${config.port}/api/payments/meta`);
+});

package/src/services/PaymentService.js

@@ -0,0 +1,249 @@
+import { v4 as uuidv4 } from "uuid";
+import { store } from "../store/MemoryStore.js";
+import { getGateway } from "../gateways/index.js";
+import { toMinorUnits, normalizeCurrency } from "../utils/money.js";
+import { AppError } from "../utils/errors.js";
+
+function scrubKeys(keys = {}) {
+  // Never persist full secrets in responses; keep only for outbound calls in memory
+  const copy = { ...keys };
+  return copy;
+}
+
+function publicPayment(payment) {
+  const { keys, ...rest } = payment;
+  return {
+    ...rest,
+    keysPresent: Boolean(keys && Object.keys(keys).length),
+  };
+}
+
+export class PaymentService {
+  async createOnlinePayment(input) {
+    const gatewayName = String(input.gateway || "").toLowerCase();
+    const currency = normalizeCurrency(input.currency);
+    const amountMinor = toMinorUnits(
+      input.amount,
+      currency,
+      Boolean(input.amountAlreadyMinor)
+    );
+
+    if (!input.keys || typeof input.keys !== "object") {
+      throw new AppError("keys object is required (gateway API credentials)");
+    }
+    if (!amountMinor || amountMinor <= 0) {
+      throw new AppError("amount must be greater than 0");
+    }
+
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    const gateway = getGateway(gatewayName);
+
+    const draft = {
+      id,
+      type: "online",
+      gateway: gateway.name,
+      orderId: input.orderId || null,
+      amount: Number(input.amount),
+      amountMinor,
+      currency,
+      description: input.description || null,
+      customer: input.customer || null,
+      paymentMethod: input.paymentMethod || null,
+      paymentMethods: input.paymentMethods || null,
+      status: "created",
+      gatewayRef: null,
+      checkoutUrl: null,
+      keys: scrubKeys(input.keys),
+      metadata: input.metadata || {},
+      createdAt: now,
+      updatedAt: now,
+      history: [{ at: now, status: "created", note: "Payment created" }],
+    };
+
+    store.savePayment(draft);
+
+    const result = await gateway.createPayment({
+      paymentId: id,
+      amountMinor,
+      currency,
+      keys: input.keys,
+      orderId: input.orderId,
+      description: input.description,
+      customer: input.customer,
+      returnUrl: input.returnUrl,
+      cancelUrl: input.cancelUrl,
+      metadata: input.metadata,
+      paymentMethod: input.paymentMethod,
+      paymentMethods: input.paymentMethods,
+      cardToken: input.cardToken,
+      bank: input.bank,
+    });
+
+    draft.status = result.status || "pending";
+    draft.gatewayRef = result.gatewayRef || null;
+    draft.checkoutUrl = result.checkoutUrl || null;
+    draft.token = result.token || null;
+    draft.clientSecret = result.clientSecret || null;
+    draft.checkout = result.checkout || null;
+    draft.qrImageUrl = result.qrImageUrl || null;
+    draft.resolvedPaymentMethods = result.paymentMethods || null;
+    draft.amountDisplay = result.amountDisplay || null;
+    draft.gatewayRaw = result.raw || null;
+    draft.updatedAt = new Date().toISOString();
+    draft.history.push({
+      at: draft.updatedAt,
+      status: draft.status,
+      note: "Gateway charge/session created",
+    });
+
+    store.savePayment(draft);
+    return publicPayment(draft);
+  }
+
+  async refreshStatus(paymentId, keysOverride) {
+    const payment = store.getPayment(paymentId);
+    if (!payment) throw new AppError("Payment not found", 404);
+    if (payment.type === "edc") {
+      return publicPayment(payment);
+    }
+
+    const keys = keysOverride || payment.keys;
+    if (!keys) throw new AppError("keys required to refresh status", 400);
+    if (!payment.gatewayRef) throw new AppError("No gateway reference to query", 400);
+
+    const gateway = getGateway(payment.gateway);
+    const result = await gateway.getStatus({
+      keys,
+      gatewayRef: payment.gatewayRef,
+      orderId: payment.orderId,
+    });
+
+    payment.status = result.status;
+    payment.gatewayRaw = result.raw;
+    payment.updatedAt = new Date().toISOString();
+    payment.history.push({
+      at: payment.updatedAt,
+      status: payment.status,
+      note: "Status refreshed from gateway",
+    });
+    // refresh stored keys if override provided
+    if (keysOverride) payment.keys = scrubKeys(keysOverride);
+    store.savePayment(payment);
+    return publicPayment(payment);
+  }
+
+  getPayment(id) {
+    const payment = store.getPayment(id);
+    if (!payment) throw new AppError("Payment not found", 404);
+    return publicPayment(payment);
+  }
+
+  listPayments() {
+    return store.listPayments().map(publicPayment);
+  }
+
+  applyWebhookUpdate({ gateway, gatewayRef, status, raw }) {
+    const payment =
+      store.findPaymentByGatewayRef(String(gateway).toLowerCase(), gatewayRef) ||
+      null;
+    if (!payment) return null;
+
+    payment.status = status;
+    payment.gatewayRaw = raw;
+    payment.updatedAt = new Date().toISOString();
+    payment.history.push({
+      at: payment.updatedAt,
+      status,
+      note: "Updated via webhook",
+    });
+    store.savePayment(payment);
+    return publicPayment(payment);
+  }
+
+  // --- Yokke EDC local-terminal flow (from integration guide) ---
+
+  createEdcAttempt(input) {
+    const currency = normalizeCurrency(input.currency || "IDR");
+    const amountMinor = toMinorUnits(
+      input.amount,
+      currency,
+      Boolean(input.amountAlreadyMinor)
+    );
+    if (!amountMinor || amountMinor <= 0) {
+      throw new AppError("amount must be greater than 0");
+    }
+
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    const attempt = {
+      id,
+      type: "edc",
+      gateway: "yokke_edc",
+      orderId: input.orderId || null,
+      deviceId: input.deviceId || null,
+      storeId: input.storeId || null,
+      amount: Number(input.amount),
+      amountMinor,
+      currency,
+      status: "awaiting_terminal",
+      terminalResult: null,
+      metadata: input.metadata || {},
+      createdAt: now,
+      updatedAt: now,
+      history: [{ at: now, status: "awaiting_terminal", note: "EDC attempt created" }],
+    };
+
+    // Also mirror into payments map for unified GET
+    store.saveAttempt(attempt);
+    store.savePayment({ ...attempt, keys: null });
+    return publicPayment(attempt);
+  }
+
+  recordTerminalResult(attemptId, result) {
+    const attempt = store.getAttempt(attemptId) || store.getPayment(attemptId);
+    if (!attempt || attempt.type !== "edc") {
+      throw new AppError("EDC payment attempt not found", 404);
+    }
+
+    const statusRaw = String(result.status || "").toLowerCase();
+    let status = "pending";
+    if (["approved", "success", "succeeded", "paid"].includes(statusRaw)) status = "succeeded";
+    else if (["declined", "failed", "cancelled", "canceled", "error"].includes(statusRaw)) {
+      status = "failed";
+    } else if (["unknown", "timeout", "pending"].includes(statusRaw)) {
+      status = "pending";
+    }
+
+    // Basic amount check when terminal echoes amount
+    if (result.amountMinor != null && Number(result.amountMinor) !== attempt.amountMinor) {
+      throw new AppError("Terminal amount does not match attempt amount", 409, {
+        expected: attempt.amountMinor,
+        received: result.amountMinor,
+      });
+    }
+
+    attempt.status = status;
+    attempt.terminalResult = {
+      approvalCode: result.approvalCode || null,
+      referenceNo: result.referenceNo || null,
+      rrn: result.rrn || null,
+      cardBrand: result.cardBrand || null,
+      maskedPan: result.maskedPan || null,
+      raw: result.raw || result,
+      verifiedAt: new Date().toISOString(),
+    };
+    attempt.updatedAt = new Date().toISOString();
+    attempt.history.push({
+      at: attempt.updatedAt,
+      status,
+      note: "Terminal result received from kiosk",
+    });
+
+    store.saveAttempt(attempt);
+    store.savePayment({ ...attempt, keys: null });
+    return publicPayment(attempt);
+  }
+}
+
+export const paymentService = new PaymentService();

package/src/store/MemoryStore.js

@@ -0,0 +1,49 @@
+/**
+ * In-memory payment store for demos / local kiosk PoC.
+ * Replace with Postgres/Redis for production.
+ */
+class MemoryStore {
+  constructor() {
+    this.payments = new Map();
+    this.attempts = new Map();
+  }
+
+  savePayment(payment) {
+    this.payments.set(payment.id, payment);
+    return payment;
+  }
+
+  getPayment(id) {
+    return this.payments.get(id) || null;
+  }
+
+  findPaymentByGatewayRef(gateway, gatewayRef) {
+    for (const p of this.payments.values()) {
+      if (p.gateway === gateway && p.gatewayRef === gatewayRef) return p;
+    }
+    return null;
+  }
+
+  listPayments(limit = 50) {
+    return [...this.payments.values()]
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .slice(0, limit);
+  }
+
+  saveAttempt(attempt) {
+    this.attempts.set(attempt.id, attempt);
+    return attempt;
+  }
+
+  getAttempt(id) {
+    return this.attempts.get(id) || null;
+  }
+
+  listAttempts(limit = 50) {
+    return [...this.attempts.values()]
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .slice(0, limit);
+  }
+}
+
+export const store = new MemoryStore();

package/src/utils/base64.js

@@ -0,0 +1,11 @@
+/** Base64 encode that works in Node and browsers. */
+export function toBase64(value) {
+  const str = String(value);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "utf8").toString("base64");
+  }
+  if (typeof btoa === "function") {
+    return btoa(unescape(encodeURIComponent(str)));
+  }
+  throw new Error("No Base64 encoder available in this environment");
+}

package/src/utils/errors.js

@@ -0,0 +1,21 @@
+export class AppError extends Error {
+  constructor(message, statusCode = 400, details = undefined) {
+    super(message);
+    this.name = "AppError";
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+}
+
+export function errorHandler(err, _req, res, _next) {
+  const status = err.statusCode || 500;
+  const body = {
+    ok: false,
+    error: err.message || "Internal server error",
+  };
+  if (err.details) body.details = err.details;
+  if (status >= 500) {
+    console.error("[error]", err);
+  }
+  res.status(status).json(body);
+}

package/src/utils/money.js

@@ -0,0 +1,75 @@
+/**
+ * Zero-decimal currencies (amount already in major units for Stripe-style APIs).
+ * IDR/VND/etc. are treated as zero-decimal for Stripe; Midtrans/Xendit have their own rules.
+ */
+const ZERO_DECIMAL = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "IDR", // Stripe + SEA gateways treat rupiah as whole units
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "UGX",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+/** Currencies commonly used with SEA / SG / MY focus */
+export const SUPPORTED_CURRENCIES = [
+  "SGD",
+  "MYR",
+  "IDR",
+  "THB",
+  "PHP",
+  "VND",
+  "USD",
+  "INR",
+  "JPY",
+  "AUD",
+  "HKD",
+];
+
+export function normalizeCurrency(currency) {
+  return String(currency || "").trim().toUpperCase();
+}
+
+export function isZeroDecimal(currency) {
+  return ZERO_DECIMAL.has(normalizeCurrency(currency));
+}
+
+/**
+ * Convert major-unit amount (e..g. 10.50 SGD) to minor units (1050).
+ * Pass amountAlreadyMinor=true if the client already sent cents/sen.
+ */
+export function toMinorUnits(amount, currency, amountAlreadyMinor = false) {
+  const cur = normalizeCurrency(currency);
+  const n = Number(amount);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new Error("Invalid amount");
+  }
+  if (amountAlreadyMinor || isZeroDecimal(cur)) {
+    return Math.round(n);
+  }
+  return Math.round(n * 100);
+}
+
+/** Convert minor units back to major for gateways that expect major units */
+export function toMajorUnits(minorAmount, currency) {
+  const cur = normalizeCurrency(currency);
+  if (isZeroDecimal(cur)) return Math.round(Number(minorAmount));
+  return Number(minorAmount) / 100;
+}
+
+export function formatMajor(minorAmount, currency) {
+  const major = toMajorUnits(minorAmount, currency);
+  if (isZeroDecimal(currency)) return String(Math.round(major));
+  return major.toFixed(2);
+}

package/src/utils/paymentMethods.js

@@ -0,0 +1,166 @@
+/**
+ * Normalize client paymentMethod / paymentMethods into gateway-specific values.
+ *
+ * Accepted aliases (any gateway):
+ *   card, qr, qris, ewallet, wallet, bank, bank_transfer, va,
+ *   paynow, promptpay, fpx, upi, gopay, grabpay, shopeepay, ovo, dana
+ */
+
+const ALIASES = {
+  card: "card",
+  credit_card: "card",
+  debit_card: "card",
+  qr: "qr",
+  qris: "qr",
+  qr_code: "qr",
+  qrcode: "qr",
+  ewallet: "ewallet",
+  wallet: "ewallet",
+  e_wallet: "ewallet",
+  bank: "bank",
+  bank_transfer: "bank",
+  va: "bank",
+  virtual_account: "bank",
+  paynow: "paynow",
+  sgqr: "sgqr",
+  promptpay: "promptpay",
+  apple_pay: "apple_pay",
+  google_pay: "google_pay",
+  fpx: "fpx",
+  upi: "upi",
+  gopay: "gopay",
+  grabpay: "grabpay",
+  shopeepay: "shopeepay",
+  ovo: "ovo",
+  dana: "dana",
+  linkaja: "linkaja",
+};
+
+export const PAYMENT_METHOD_HINTS = {
+  common: ["card", "qr", "ewallet", "bank", "paynow", "promptpay", "fpx", "upi"],
+  xendit: {
+    card: ["CREDIT_CARD"],
+    // "qr" is remapped by currency below (SGD→PAYNOW, IDR→QRIS, THB→PROMPTPAY)
+    qr: ["QRIS"],
+    ewallet: ["GRABPAY", "OVO", "DANA", "LINKAJA", "SHOPEEPAY", "GCASH", "PAYMAYA"],
+    bank: ["VIRTUAL_ACCOUNT", "DIRECT_DEBIT"],
+    paynow: ["PAYNOW"],
+    sgqr: ["PAYNOW"],
+    promptpay: ["PROMPTPAY"],
+    grabpay: ["GRABPAY"],
+    ovo: ["OVO"],
+    dana: ["DANA"],
+    shopeepay: ["SHOPEEPAY"],
+    apple_pay: ["CREDIT_CARD"],
+    google_pay: ["CREDIT_CARD"],
+  },
+  midtrans: {
+    card: ["credit_card"],
+    qr: ["qris", "gopay", "shopeepay"],
+    ewallet: ["gopay", "shopeepay", "other_qris"],
+    bank: ["bank_transfer", "echannel", "permata_va", "bca_va", "bni_va", "bri_va"],
+    gopay: ["gopay"],
+    shopeepay: ["shopeepay"],
+  },
+  stripe: {
+    card: ["card"],
+    qr: ["paynow", "promptpay", "alipay"],
+    ewallet: ["grabpay", "alipay", "wechat_pay"],
+    bank: ["fpx", "paynow"],
+    paynow: ["paynow"],
+    promptpay: ["promptpay"],
+    fpx: ["fpx"],
+    grabpay: ["grabpay"],
+  },
+  razorpay: {
+    card: ["card"],
+    qr: ["upi"],
+    ewallet: ["wallet"],
+    bank: ["netbanking"],
+    upi: ["upi"],
+  },
+  omise: {
+    card: ["card"],
+    qr: ["promptpay", "paynow"],
+    ewallet: ["truemoney", "alipay"],
+    bank: ["fpx", "internet_banking_bay", "internet_banking_bbl"],
+    paynow: ["paynow"],
+    promptpay: ["promptpay"],
+    fpx: ["fpx"],
+  },
+};
+
+export function normalizeMethods(paymentMethod, paymentMethods) {
+  const list = [];
+  if (paymentMethod) list.push(paymentMethod);
+  if (Array.isArray(paymentMethods)) list.push(...paymentMethods);
+  if (typeof paymentMethods === "string") list.push(paymentMethods);
+
+  const out = [];
+  for (const raw of list) {
+    const key = String(raw || "")
+      .trim()
+      .toLowerCase()
+      .replace(/\s+/g, "_");
+    if (!key) continue;
+    const canon = ALIASES[key] || key;
+    if (!out.includes(canon)) out.push(canon);
+  }
+  return out;
+}
+
+export function mapMethodsForGateway(gateway, methods, currency) {
+  const gw = String(gateway || "").toLowerCase();
+  const table = PAYMENT_METHOD_HINTS[gw] || {};
+  const mapped = [];
+
+  for (const m of methods) {
+    const values = table[m];
+    if (values) {
+      for (const v of values) {
+        if (!mapped.includes(v)) mapped.push(v);
+      }
+      continue;
+    }
+    // pass-through vendor-specific codes (e.g. CREDIT_CARD, qris, paynow)
+    if (!mapped.includes(m)) mapped.push(m);
+  }
+
+  const cur = String(currency || "").toUpperCase();
+
+  // Currency-aware QR / ewallet mapping (SG account has PAYNOW + cards, not QRIS/OVO)
+  if (gw === "xendit") {
+    const out = [];
+    for (const m of methods) {
+      if (m === "qr" || m === "paynow" || m === "sgqr") {
+        if (cur === "SGD") out.push("PAYNOW");
+        else if (cur === "THB") out.push("PROMPTPAY");
+        else out.push("QRIS");
+        continue;
+      }
+      if (m === "ewallet") {
+        if (cur === "SGD") out.push("GRABPAY");
+        else out.push("OVO", "DANA", "LINKAJA", "SHOPEEPAY", "GRABPAY");
+        continue;
+      }
+      if (m === "card") {
+        out.push("CREDIT_CARD");
+        continue;
+      }
+      const values = table[m];
+      if (values) out.push(...values);
+      else out.push(m);
+    }
+    return [...new Set(out)];
+  }
+
+  if (methods.includes("qr") && mapped.length) {
+    if (gw === "omise" || gw === "stripe") {
+      if (cur === "SGD") return ["paynow"];
+      if (cur === "THB") return ["promptpay"];
+      if (cur === "MYR" && gw === "stripe") return ["fpx"];
+    }
+  }
+
+  return mapped;
+}