multi-payment-system 0.0.0-stage → 1.1.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,361 @@
-# 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.
+Payments for **Node** and **React** — Xendit, Midtrans, Razorpay, Stripe, Omise (+ Yokke EDC helpers).
+
+| Import | Use in |
+|--------|--------|
+| `multi-payment-system` | Node / backend (`XenditGateway`, `charge`) |
+| `multi-payment-system/client` | React / browser (`PaymentClient`) |
+| `multi-payment-system/react` | React hook (`usePaymentClient`) |
+
+---
+
+## React client
+
+```bash
+npm install multi-payment-system
+```
+
+1. Run the payment API (`npm start` in this repo) so React has a backend.
+2. In React:
+
+```jsx
+import { usePaymentClient } from "multi-payment-system/react";
+
+export function PayButton() {
+  const { chargeAndRedirect, loading, error } = usePaymentClient({
+    baseUrl: import.meta.env.VITE_PAY_API || "http://localhost:3000",
+  });
+
+  return (
+    <button
+      disabled={loading}
+      onClick={() =>
+        chargeAndRedirect({
+          gateway: "xendit",
+          amount: 30,
+          currency: "SGD",
+          paymentMethod: "card",
+          keys: { secretKey: import.meta.env.VITE_XENDIT_SECRET }, // demo only — prefer server-held keys
+          returnUrl: window.location.origin + "/success",
+          cancelUrl: window.location.origin + "/cancel",
+        })
+      }
+    >
+      {loading ? "Opening…" : "Pay with card"}
+    </button>
+  );
+}
+```
+
+Or without the hook:
+
+```js
+import { PaymentClient, redirectToCheckout } from "multi-payment-system/client";
+
+const client = new PaymentClient({ baseUrl: "http://localhost:3000" });
+const { payment } = await client.charge({ /* same body as Postman */ });
+redirectToCheckout(payment); // opens Xendit/Stripe checkout
+```
+
+**Security:** do not ship production secret keys in a React bundle. Put keys on the server and have the client call your API without secrets.
+
+---
+
+## Node / backend SDK
+
+```js
+import { XenditGateway, charge } 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",
+});
+```
+
+---
+
+## Run local API server
+
+```bash
+npm install
+npm start
+```
+
+Server: `http://localhost:3000`
+
+```bash
+npm run test:smoke
+```
+
+### 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,74 @@
 {
   "name": "multi-payment-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Multi-gateway payments for Node and React (Xendit, Midtrans, Razorpay, Stripe, Omise)",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "react-native": "./src/client/index.js",
+  "browser": {
+    "./src/index.js": "./src/client/index.js",
+    "./src/server.js": false,
+    "./src/app.js": false,
+    "./src/config.js": false,
+    "express": false,
+    "cors": false,
+    "dotenv": false,
+    "zod": false
+  },
+  "exports": {
+    ".": {
+      "browser": "./src/client/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./client": "./src/client/index.js",
+    "./react": "./src/client/react.js",
+    "./server": "./src/server.js",
+    "./app": "./src/app.js",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test:smoke": "node scripts/smoke-test.js",
+    "test:package": "node scripts/package-import-test.js",
+    "prepublishOnly": "npm run test:package && npm run test:smoke"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "payment",
+    "react",
+    "xendit",
+    "midtrans",
+    "razorpay",
+    "stripe",
+    "omise",
+    "checkout"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "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,102 @@
+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";
+
+function newId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `pay_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Create a payment on any supported gateway.
+ * Prefer calling this on a server/backend — never ship secret keys in a React bundle.
+ */
+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 || newId();
+  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. */
+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,
+  };
+}
+
+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;
+}