multi-payment-system 0.0.0-stage → 1.0.0

package/src/index.js

@@ -0,0 +1,47 @@
+/**
+ * multi-payment-system
+ *
+ * @example
+ * import { XenditGateway, charge, getStatus } from "multi-payment-system";
+ *
+ * const xendit = new XenditGateway();
+ * const pay = await xendit.createPayment({ ... });
+ *
+ * // or one-liner helpers:
+ * const result = await charge({ gateway: "xendit", amount: 30, currency: "SGD", keys: {...}, paymentMethod: "card" });
+ */
+
+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";

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;

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,251 @@
+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.xenditPaymentMethods = result.xenditPaymentMethods || null;
+    draft.warning = result.warning || 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/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);
+}