multi-payment-system 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,351 @@
-# Temporary Holding Version
+# multi-payment-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+npm package + optional Express server for **Xendit, Midtrans, Razorpay, Stripe, Omise** (SG / MY / SEA), plus Yokke EDC attempt helpers.
+
+---
+
+## Install (as a library)
+
+```bash
+npm install multi-payment-system
+```
+
+### Use gateways as classes
+
+```js
+import { XenditGateway, StripeGateway, charge, getStatus, listGateways } from "multi-payment-system";
+
+const xendit = new XenditGateway();
+const pay = await xendit.createPayment({
+  paymentId: "pay_1",
+  amountMinor: 3000, // SGD 30.00
+  currency: "SGD",
+  paymentMethod: "card",
+  keys: { secretKey: process.env.XENDIT_SECRET_KEY },
+  returnUrl: "https://example.com/success",
+  cancelUrl: "https://example.com/cancel",
+});
+
+console.log(pay.checkoutUrl);
+```
+
+### Or one-liner helpers
+
+```js
+import { charge, getStatus } from "multi-payment-system";
+
+const result = await charge({
+  gateway: "xendit",
+  amount: 30,
+  currency: "SGD",
+  paymentMethod: "card",
+  keys: { secretKey: process.env.XENDIT_SECRET_KEY },
+  returnUrl: "https://example.com/success",
+});
+
+const status = await getStatus({
+  gateway: "xendit",
+  gatewayRef: result.gatewayRef,
+  keys: { secretKey: process.env.XENDIT_SECRET_KEY },
+});
+```
+
+### Exports
+
+| Export | What |
+|--------|------|
+| `XenditGateway`, `MidtransGateway`, `RazorpayGateway`, `StripeGateway`, `OmiseGateway` | Gateway classes |
+| `charge`, `getStatus`, `listGateways` | Helper functions |
+| `getGateway("xendit")` | Resolve by name |
+| `createApp()` | Express app (HTTP API) |
+| `PaymentService` | In-memory payment tracker used by the server |
+
+### Publish to npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+---
+
+## Run as a local server
+
+```bash
+npm install
+npm start
+```
+
+Server: `http://localhost:3000`
+
+```bash
+npm run test:smoke   # local EDC + validation checks (no real gateway keys needed)
+```
+
+### Postman
+
+Import these files into Postman:
+
+1. `postman/YOKKE_EDC_Payment_Server.postman_collection.json`
+2. `postman/YOKKE_Local.postman_environment.json`
+
+Select environment **YOKKE Local**, put your test keys in the environment variables, then run:
+
+1. **Health** (no keys needed)
+2. **Create EDC attempt** → **Report terminal result** (no gateway keys)
+3. Or **Charge - Stripe / Xendit / …** after filling keys
+
+---
+
+## How it fits the kiosk diagram
+
+```
+WebView → Kotlin Bridge → (A) this server  OR  (B) Yokke EDC via USB
+                │
+                ├─ online: POST /api/payments/charge  (Xendit/Stripe/…)
+                └─ EDC:    POST /api/payments/attempts
+                           then POST .../terminal-result after EDC responds
+```
+
+---
+
+## Amount rules
+
+| Field | Meaning |
+|--------|---------|
+| `amount` | Major units by default (`10.50` SGD = S$10.50) |
+| `amountAlreadyMinor: true` | Treat `amount` as cents/sen/paise already (`1050`) |
+| `currency` | ISO code: `SGD`, `MYR`, `IDR`, `THB`, `PHP`, `VND`, `USD`, `INR`, … |
+
+Zero-decimal currencies (e.g. `IDR`, `VND`, `JPY`) use whole major units as the charge amount.
+
+---
+
+## Create an online payment
+
+`POST /api/payments/charge`
+
+### Payment method (all gateways)
+
+Send one or both:
+
+```json
+"paymentMethod": "qr",
+"paymentMethods": ["qr", "card"]
+```
+
+Common values: `card`, `qr`, `ewallet`, `bank`, `paynow`, `promptpay`, `fpx`, `upi`, `gopay`, `grabpay`, `ovo`, `dana`, `shopeepay`.
+
+| Value | Typical meaning |
+|-------|-----------------|
+| `card` | Credit/debit card |
+| `qr` | QRIS / PayNow / PromptPay / UPI QR (mapped per gateway + currency) |
+| `ewallet` | OVO, DANA, GrabPay, etc. |
+| `bank` | VA / FPX / bank transfer |
+
+### Stripe (SG / MY / global)
+
+```json
+{
+  "gateway": "stripe",
+  "amount": 12.5,
+  "currency": "SGD",
+  "paymentMethod": "qr",
+  "keys": { "secretKey": "sk_test_..." },
+  "orderId": "order-1001",
+  "description": "Kiosk order 1001",
+  "returnUrl": "https://your-app/success?session_id={CHECKOUT_SESSION_ID}",
+  "cancelUrl": "https://your-app/cancel",
+  "customer": { "email": "buyer@example.com" }
+}
+```
+
+### Xendit (SG / MY / ID / PH / TH / VN)
+
+```json
+{
+  "gateway": "xendit",
+  "amount": 25,
+  "currency": "SGD",
+  "paymentMethod": "qr",
+  "paymentMethods": ["qr", "card"],
+  "keys": { "secretKey": "xnd_development_..." },
+  "orderId": "order-1002",
+  "returnUrl": "https://your-app/success",
+  "customer": { "email": "buyer@example.com" }
+}
+```
+
+### Midtrans (Indonesia)
+
+```json
+{
+  "gateway": "midtrans",
+  "amount": 50000,
+  "currency": "IDR",
+  "keys": {
+    "serverKey": "SB-Mid-server-...",
+    "isProduction": false
+  },
+  "orderId": "order-1003",
+  "returnUrl": "https://your-app/finish"
+}
+```
+
+### Razorpay
+
+```json
+{
+  "gateway": "razorpay",
+  "amount": 100,
+  "currency": "INR",
+  "amountAlreadyMinor": true,
+  "keys": {
+    "keyId": "rzp_test_...",
+    "keySecret": "..."
+  },
+  "orderId": "order-1004"
+}
+```
+
+Response includes `payment.checkout` for opening Razorpay Checkout in the WebView.
+
+### Omise / Opn (SG PayNow, MY FPX, TH PromptPay)
+
+```json
+{
+  "gateway": "omise",
+  "amount": 15,
+  "currency": "SGD",
+  "paymentMethod": "paynow",
+  "keys": { "secretKey": "skey_test_..." },
+  "returnUrl": "https://your-app/return",
+  "orderId": "order-1005"
+}
+```
+
+For Malaysia FPX:
+
+```json
+{
+  "gateway": "omise",
+  "amount": 20,
+  "currency": "MYR",
+  "paymentMethod": "fpx",
+  "keys": { "secretKey": "skey_test_...", "bank": "uob" },
+  "returnUrl": "https://your-app/return"
+}
+```
+
+### Success response (shape)
+
+```json
+{
+  "ok": true,
+  "payment": {
+    "id": "uuid",
+    "gateway": "stripe",
+    "status": "pending",
+    "checkoutUrl": "https://checkout.stripe.com/...",
+    "amount": 12.5,
+    "amountMinor": 1250,
+    "currency": "SGD"
+  }
+}
+```
+
+Open `checkoutUrl` in the kiosk WebView (or system browser). Then poll:
+
+- `GET /api/payments/:id`
+- or `POST /api/payments/:id/refresh` with `{ "keys": { ... } }` if you did not keep keys server-side
+
+---
+
+## Yokke EDC local terminal flow
+
+### 1. Create attempt (before talking to the EDC)
+
+```http
+POST /api/payments/attempts
+```
+
+```json
+{
+  "amount": 75000,
+  "currency": "IDR",
+  "orderId": "order-2001",
+  "deviceId": "kiosk-storeA-01"
+}
+```
+
+### 2. Kotlin sends sale to EDC over USB/serial
+
+### 3. Report verified terminal result
+
+```http
+POST /api/payments/attempts/{id}/terminal-result
+```
+
+```json
+{
+  "status": "approved",
+  "approvalCode": "00",
+  "referenceNo": "123456",
+  "rrn": "999888",
+  "amountMinor": 75000
+}
+```
+
+Only mark the order paid when this returns `status: "succeeded"`.
+
+---
+
+## Webhooks (optional)
+
+Point each gateway dashboard to:
+
+| Gateway   | URL |
+|-----------|-----|
+| Xendit    | `POST /webhooks/xendit` |
+| Midtrans  | `POST /webhooks/midtrans` |
+| Razorpay  | `POST /webhooks/razorpay` |
+| Stripe    | `POST /webhooks/stripe` |
+| Omise     | `POST /webhooks/omise` |
+
+Use a public tunnel (`PUBLIC_BASE_URL`) in development.
+
+---
+
+## Optional API key
+
+Set in `.env`:
+
+```
+API_KEY=change-me-kiosk-api-key
+```
+
+Then send header: `x-api-key: change-me-kiosk-api-key`
+
+---
+
+## Project layout
+
+```
+src/
+  index.js                 # starts server
+  app.js                   # Express app
+  gateways/                # Xendit, Midtrans, Razorpay, Stripe, Omise
+  routes/payments.js       # charge + EDC endpoints
+  routes/webhooks.js
+  services/PaymentService.js
+  store/MemoryStore.js     # swap for DB in production
+```
+
+---
+
+## Production notes
+
+- Replace `MemoryStore` with Postgres/Redis.
+- Prefer storing merchant keys encrypted server-side (vault) instead of accepting raw secrets on every request long-term.
+- Never log full card data from EDC responses.
+- Confirm Yokke EDC model / protocol before production USB framing (see the integration guide).

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "multi-payment-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Multi-gateway payment SDK + optional Express server (Xendit, Midtrans, Razorpay, Stripe, Omise)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./app": "./src/app.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test:smoke": "node scripts/smoke-test.js",
+    "prepublishOnly": "node scripts/smoke-test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "payment",
+    "xendit",
+    "midtrans",
+    "razorpay",
+    "stripe",
+    "omise",
+    "sgd",
+    "myr",
+    "kiosk",
+    "gateway"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "axios": "^1.7.9",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "uuid": "^11.0.5",
+    "zod": "^3.24.1"
+  }
+}

package/src/api.js

@@ -0,0 +1,117 @@
+import { v4 as uuidv4 } from "uuid";
+import { getGateway, GATEWAY_NAMES, gatewayRegionsHint } from "./gateways/index.js";
+import { toMinorUnits, normalizeCurrency, SUPPORTED_CURRENCIES } from "./utils/money.js";
+import { PAYMENT_METHOD_HINTS, normalizeMethods } from "./utils/paymentMethods.js";
+import { AppError } from "./utils/errors.js";
+
+/**
+ * Create a payment on any supported gateway.
+ *
+ * @example
+ * import { charge } from "multi-payment-system";
+ * const result = await charge({
+ *   gateway: "xendit",
+ *   amount: 30,
+ *   currency: "SGD",
+ *   paymentMethod: "card",
+ *   keys: { secretKey: "xnd_development_..." },
+ *   returnUrl: "https://example.com/success",
+ * });
+ */
+export async function charge(input = {}) {
+  const gatewayName = String(input.gateway || "").toLowerCase();
+  if (!gatewayName) throw new AppError("gateway is required");
+
+  const currency = normalizeCurrency(input.currency);
+  if (!currency) throw new AppError("currency is required");
+
+  if (!input.keys || typeof input.keys !== "object") {
+    throw new AppError("keys object is required (gateway API credentials)");
+  }
+
+  const amountMinor = toMinorUnits(
+    input.amount,
+    currency,
+    Boolean(input.amountAlreadyMinor)
+  );
+  if (!amountMinor || amountMinor <= 0) {
+    throw new AppError("amount must be greater than 0");
+  }
+
+  const paymentId = input.paymentId || uuidv4();
+  const gateway = getGateway(gatewayName);
+
+  const result = await gateway.createPayment({
+    paymentId,
+    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,
+  });
+
+  return {
+    ok: true,
+    paymentId,
+    gateway: gateway.name,
+    amount: Number(input.amount),
+    amountMinor,
+    currency,
+    paymentMethod: input.paymentMethod || null,
+    paymentMethods: normalizeMethods(input.paymentMethod, input.paymentMethods),
+    ...result,
+  };
+}
+
+/**
+ * Refresh / query payment status from the gateway.
+ *
+ * @example
+ * import { getStatus } from "multi-payment-system";
+ * const status = await getStatus({
+ *   gateway: "xendit",
+ *   gatewayRef: "inv_...",
+ *   keys: { secretKey: "xnd_development_..." },
+ * });
+ */
+export async function getStatus(input = {}) {
+  const gatewayName = String(input.gateway || "").toLowerCase();
+  if (!gatewayName) throw new AppError("gateway is required");
+  if (!input.gatewayRef && !input.orderId) {
+    throw new AppError("gatewayRef (or orderId for Midtrans) is required");
+  }
+  if (!input.keys || typeof input.keys !== "object") {
+    throw new AppError("keys object is required");
+  }
+
+  const gateway = getGateway(gatewayName);
+  const result = await gateway.getStatus({
+    keys: input.keys,
+    gatewayRef: input.gatewayRef,
+    orderId: input.orderId,
+  });
+
+  return {
+    ok: true,
+    gateway: gateway.name,
+    ...result,
+  };
+}
+
+/** List supported gateways, regions, currencies, payment method hints */
+export function listGateways() {
+  return {
+    gateways: GATEWAY_NAMES,
+    regions: gatewayRegionsHint(),
+    currencies: SUPPORTED_CURRENCIES,
+    paymentMethods: PAYMENT_METHOD_HINTS,
+  };
+}

package/src/app.js

@@ -0,0 +1,43 @@
+import express from "express";
+import cors from "cors";
+import paymentsRouter from "./routes/payments.js";
+import webhooksRouter from "./routes/webhooks.js";
+import { optionalApiKey } from "./middleware/auth.js";
+import { errorHandler } from "./utils/errors.js";
+import { GATEWAY_NAMES, gatewayRegionsHint } from "./gateways/index.js";
+
+export function createApp() {
+  const app = express();
+
+  app.use(cors());
+  app.use(express.json({ limit: "1mb" }));
+  app.use(express.urlencoded({ extended: true }));
+
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true, service: "yokke-edc-payment-server", time: new Date().toISOString() });
+  });
+
+  app.get("/", (_req, res) => {
+    res.json({
+      ok: true,
+      name: "YOKKE EDC + Multi-Gateway Payment Server",
+      gateways: GATEWAY_NAMES,
+      regions: gatewayRegionsHint(),
+      endpoints: {
+        meta: "GET /api/payments/meta",
+        charge: "POST /api/payments/charge",
+        get: "GET /api/payments/:id",
+        refresh: "POST /api/payments/:id/refresh",
+        edcAttempt: "POST /api/payments/attempts",
+        terminalResult: "POST /api/payments/attempts/:id/terminal-result",
+        webhooks: "POST /webhooks/{xendit|midtrans|razorpay|stripe|omise}",
+      },
+    });
+  });
+
+  app.use("/api/payments", optionalApiKey, paymentsRouter);
+  app.use("/webhooks", webhooksRouter);
+
+  app.use(errorHandler);
+  return app;
+}

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";
+  }
+}