9pay-integrate 1.0.0

package/README.md

@@ -0,0 +1,241 @@
+# 9pay-integrate
+
+Complete 9Pay payment gateway integration for Node.js and Next.js. Generate payment URLs, verify callbacks, process IPN webhooks — all with a clean, framework-agnostic core.
+
+```bash
+pnpm install 9pay-integrate
+```
+
+## Quick Start
+
+### 1. Configure
+
+```typescript
+// lib/9pay-config.ts
+import { configFromEnv } from "9pay-integrate";
+
+export const ninepay = configFromEnv(process.env);
+```
+
+Required environment variables:
+- `NINEPAY_MERCHANT_KEY`
+- `NINEPAY_SECRET_KEY`
+- `NINEPAY_CHECKSUM_KEY`
+- `NINEPAY_RETURN_URL` (e.g. `https://yoursite.com/api/checkout/9pay/callback`)
+
+Optional:
+- `NINEPAY_BASE_URL` (default: `https://payment.9pay.vn`)
+- `NINEPAY_CANCEL_URL` (default: same as RETURN_URL)
+
+### 2. Implement Order Repository
+
+The package needs a way to manage orders. Implement the `OrderRepository` interface for your data layer (Strapi, Prisma, Drizzle, MongoDB, REST API, etc.).
+
+```typescript
+// lib/order-repository.ts
+import type { OrderRepository, OrderStatus } from "9pay-integrate";
+
+export const repo: OrderRepository = {
+  async createOrder(params) {
+    // Create order in your database
+    // Return whatever your DB returns
+  },
+  async getOrderStatus(orderId: string): Promise<OrderStatus | null> {
+    // Query order status from your database
+    // Return "neworder" | "pending" | "completed" | "failed" | null
+  },
+  async updateOrderStatus(orderId: string, status: "completed" | "failed") {
+    // Update order status in your database
+    // Return the updated order or null
+  },
+};
+```
+
+### 3. Implement Notification Hooks (optional)
+
+```typescript
+// lib/notifications.ts
+import type { NotificationContext } from "9pay-integrate";
+
+export const notifications = {
+  async onSuccess(ctx: NotificationContext) {
+    // Send confirmation email
+    // Send Telegram/Slack notification
+    console.log(`Order ${ctx.orderId} completed: ${ctx.amount} ${ctx.currency}`);
+  },
+  async onFailure(ctx: NotificationContext) {
+    // Alert on payment failure
+    console.log(`Order ${ctx.orderId} failed`);
+  },
+};
+```
+
+### 4. Create Payment URL (Checkout POST)
+
+In your checkout API route, create the order in your database, then generate the 9Pay redirect URL.
+
+```typescript
+// app/api/checkout/route.ts
+import { NextResponse } from "next/server";
+import { createPaymentUrl } from "9pay-integrate";
+import { ninepay } from "@/lib/9pay-config";
+import { repo } from "@/lib/order-repository";
+
+export async function POST(request: Request) {
+  const body = await request.json();
+
+  // 1. Validate checkout form data, calculate pricing, etc.
+  // 2. Create order in your database
+  const order = await repo.createOrder({
+    totalAmount: body.amount,
+    currency: body.currency,
+    paymentMethod: "9pay",
+    metadata: body,
+  });
+
+  // 3. Generate 9Pay payment URL
+  const paymentUrl = createPaymentUrl(ninepay, {
+    orderId: order.id, // or order.documentId, whatever your DB returns
+    amount: body.amount,
+    currency: body.currency,
+    description: "Order Payment",
+  });
+
+  return NextResponse.json({ success: true, orderId: order.id, paymentUrl });
+}
+```
+
+### 5. Wire Up Routes
+
+#### Callback Route (GET)
+
+Handles the browser redirect after payment on 9Pay's portal.
+
+```typescript
+// app/api/checkout/9pay/callback/route.ts
+import { NextResponse } from "next/server";
+import { verifyNinePayCallback } from "9pay-integrate/next";
+import { ninepay } from "@/lib/9pay-config";
+
+export async function GET(request: Request) {
+  const result = verifyNinePayCallback(request, ninepay);
+
+  if (!result.success) {
+    return NextResponse.redirect(new URL("/payment/error", request.url));
+  }
+
+  return NextResponse.redirect(
+    new URL(`/payment/process?orderId=${result.orderId}`, request.url)
+  );
+}
+```
+
+#### IPN Webhook (POST)
+
+Handles the server-to-server webhook from 9Pay. This is the source of truth for payment status.
+
+```typescript
+// app/api/checkout/9pay/ipn/route.ts
+import { handle9PayIpn } from "9pay-integrate/next";
+import { ninepay } from "@/lib/9pay-config";
+import { repo } from "@/lib/order-repository";
+import { notifications } from "@/lib/notifications";
+
+export async function POST(request: Request) {
+  return handle9PayIpn(request, {
+    config: ninepay,
+    orderRepository: repo,
+    notifications,
+  });
+}
+```
+
+#### Payment Status (GET)
+
+For frontend polling.
+
+```typescript
+// app/api/payment/status/route.ts
+import { handlePaymentStatus } from "9pay-integrate/next";
+import { repo } from "@/lib/order-repository";
+
+export async function GET(request: Request) {
+  return handlePaymentStatus(request, { orderRepository: repo });
+}
+```
+
+## API Reference
+
+### Core (`9pay-integrate`)
+
+| Export | Description |
+|--------|-------------|
+| `configFromEnv(env)` | Build config from any env-like object |
+| `validateConfig(partial)` | Validate and normalize config |
+| `createPaymentUrl(config, params)` | Generate signed 9Pay redirect URL |
+| `verifyChecksum(result, checksum, key)` | Verify callback/IPN checksum |
+| `verifyCallback(searchParams, config)` | Verify browser redirect callback |
+| `processIpn(payload, options)` | Process IPN (adapter-agnostic) |
+| `buildHttpQuery(data)` | Build sorted query string (advanced) |
+| `buildSignature(baseUrl, time, query, key)` | Build HMAC signature (advanced) |
+| `extractIpnFromFormData(formData)` | Extract IPN from FormData |
+| `extractIpnFromUrlEncoded(body)` | Extract IPN from URL-encoded body |
+| `NINEPAY_STATUS` | Status codes (SUCCESS = 5) |
+| `SUCCESS_STATUS` | Constant for successful payment |
+
+### Next.js Adapter (`9pay-integrate/next`)
+
+| Export | Description |
+|--------|-------------|
+| `verifyNinePayCallback(request, config)` | Verify callback, return result object |
+| `handle9PayIpn(request, options)` | Full IPN handler → NextResponse |
+| `handlePaymentStatus(request, options)` | Status polling handler → NextResponse |
+
+### Types
+
+All types are exported from the main entry point. Key interfaces:
+
+- `NinePayConfig` — configuration
+- `OrderRepository` — implement for your data layer
+- `NotificationHooks` — optional notification callbacks
+- `IpnProcessResult` — IPN processing result
+- `VerifyCallbackResult` — callback verification result
+- `OrderStatus` — `"neworder" | "pending" | "completed" | "failed"`
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           9Pay Portal                    │
+│      payment.9pay.vn/portal              │
+└────────────┬────────────────┬───────────┘
+             │                │
+      Browser redirect    Server-to-server
+        (callback GET)        (IPN POST)
+             │                │
+┌────────────▼────────────────▼───────────┐
+│              9pay-integrate/core         │
+│  ┌─────────┐  ┌───────────┐  ┌───────┐  │
+│  │ signing  │  │ verify    │  │ ipn   │  │
+│  │ +payment │  │ callback  │  │ proc  │  │
+│  └─────────┘  └───────────┘  └───────┘  │
+│            (zero framework deps)         │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│          9pay-integrate/next             │
+│  (thin glue: parse req → call core)      │
+└─────────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Core has zero framework dependencies** — works in Express, Fastify, Hono, Bun, Deno
+2. **Inversion of Control** — package never hardcodes ORM/CMS/notification service
+3. **Option B for callback** — returns data, consumer controls redirect
+4. **Option C for IPN** — encapsulates all 6 steps, but consumer can bypass and call `processIpn()` directly from core
+5. **Fail fast** — config validation at init time, not during live payment
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,317 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  NINEPAY_STATUS: () => NINEPAY_STATUS,
+  SUCCESS_STATUS: () => SUCCESS_STATUS,
+  buildHttpQuery: () => buildHttpQuery,
+  buildSignature: () => buildSignature,
+  configFromEnv: () => configFromEnv,
+  createPaymentUrl: () => createPaymentUrl,
+  extractIpnFromFormData: () => extractIpnFromFormData,
+  extractIpnFromUrlEncoded: () => extractIpnFromUrlEncoded,
+  processIpn: () => processIpn,
+  validateConfig: () => validateConfig,
+  verifyCallback: () => verifyCallback,
+  verifyChecksum: () => verifyChecksum
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/constants.ts
+var NINEPAY_STATUS = {
+  PENDING: 1,
+  PROCESSING: 2,
+  CANCELLED: 3,
+  REFUNDED: 4,
+  SUCCESS: 5,
+  FAILED: 6
+};
+var SUCCESS_STATUS = NINEPAY_STATUS.SUCCESS;
+var DEFAULT_BASE_URL = "https://payment.9pay.vn";
+
+// src/core/config.ts
+function validateConfig(config) {
+  const errors = [];
+  if (!config.merchantKey) errors.push("merchantKey is required");
+  if (!config.secretKey) errors.push("secretKey is required");
+  if (!config.checksumKey) errors.push("checksumKey is required");
+  if (!config.returnUrl) errors.push("returnUrl is required");
+  if (errors.length > 0) {
+    throw new Error(
+      `9pay-integrate configuration error:
+  - ${errors.join("\n  - ")}`
+    );
+  }
+  return {
+    merchantKey: config.merchantKey,
+    secretKey: config.secretKey,
+    checksumKey: config.checksumKey,
+    baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+    returnUrl: config.returnUrl,
+    cancelUrl: config.cancelUrl || config.returnUrl
+  };
+}
+function configFromEnv(env) {
+  return validateConfig({
+    merchantKey: env.NINEPAY_MERCHANT_KEY,
+    secretKey: env.NINEPAY_SECRET_KEY,
+    checksumKey: env.NINEPAY_CHECKSUM_KEY,
+    baseUrl: env.NINEPAY_BASE_URL,
+    returnUrl: env.NINEPAY_RETURN_URL,
+    cancelUrl: env.NINEPAY_CANCEL_URL
+  });
+}
+
+// src/core/signing.ts
+var crypto = __toESM(require("crypto"), 1);
+function buildHttpQuery(data) {
+  const params = new URLSearchParams();
+  const sortedKeys = Object.keys(data).sort();
+  for (const key of sortedKeys) {
+    if (data[key] !== void 0 && data[key] !== null) {
+      params.append(key, String(data[key]));
+    }
+  }
+  return params.toString();
+}
+function buildSignature(baseUrl, time, httpQuery, secretKey) {
+  const message = `POST
+${baseUrl}/payments/create
+${time}
+${httpQuery}`;
+  return crypto.createHmac("sha256", secretKey).update(message).digest().toString("base64");
+}
+
+// src/core/payment-url.ts
+function createPaymentUrl(config, params) {
+  const time = Math.floor(Date.now() / 1e3);
+  const parameters = {
+    merchantKey: config.merchantKey,
+    time,
+    invoice_no: params.orderId,
+    amount: params.amount,
+    currency: params.currency,
+    description: params.description,
+    return_url: config.returnUrl,
+    ...config.cancelUrl ? { back_url: config.cancelUrl } : {},
+    ...params.options
+  };
+  const httpQuery = buildHttpQuery(parameters);
+  const signature = buildSignature(
+    config.baseUrl || "https://payment.9pay.vn",
+    time,
+    httpQuery,
+    config.secretKey
+  );
+  const sortedParameters = {};
+  Object.keys(parameters).sort().forEach((key) => {
+    sortedParameters[key] = parameters[key];
+  });
+  const baseEncode = Buffer.from(JSON.stringify(sortedParameters)).toString(
+    "base64"
+  );
+  const redirectParams = new URLSearchParams({ baseEncode, signature });
+  return `${config.baseUrl || "https://payment.9pay.vn"}/portal?${redirectParams.toString()}`;
+}
+
+// src/core/verification.ts
+var crypto2 = __toESM(require("crypto"), 1);
+function verifyChecksum(result, checksum, checksumKey) {
+  if (!result || !checksum) {
+    return { valid: false, data: null, error: "Missing result or checksum" };
+  }
+  const expected = crypto2.createHash("sha256").update(result + checksumKey).digest("hex").toUpperCase();
+  if (expected !== checksum) {
+    return { valid: false, data: null, error: "Checksum mismatch" };
+  }
+  try {
+    const decoded = JSON.parse(
+      Buffer.from(result, "base64").toString("utf-8")
+    );
+    return { valid: true, data: decoded };
+  } catch {
+    return { valid: false, data: null, error: "Failed to decode result" };
+  }
+}
+
+// src/core/verify-callback.ts
+function verifyCallback(searchParams, config) {
+  const result = searchParams.get("result") || "";
+  const checksum = searchParams.get("checksum") || "";
+  const verification = verifyChecksum(result, checksum, config.checksumKey);
+  if (!verification.valid || !verification.data) {
+    return {
+      success: false,
+      rawParams: {},
+      error: verification.error || "Invalid callback payload"
+    };
+  }
+  const paymentInfo = verification.data;
+  const invoiceNo = paymentInfo.invoice_no;
+  const orderId = typeof invoiceNo === "string" && invoiceNo.trim().length > 0 ? invoiceNo : typeof invoiceNo === "number" ? String(invoiceNo) : null;
+  if (!orderId) {
+    return {
+      success: false,
+      rawParams: paymentInfo,
+      error: "Missing invoice_no in callback payload"
+    };
+  }
+  return {
+    success: true,
+    orderId,
+    amount: Number(paymentInfo.amount ?? 0),
+    currency: String(paymentInfo.currency ?? ""),
+    status: Number(paymentInfo.status ?? 0),
+    rawParams: paymentInfo
+  };
+}
+
+// src/core/ipn.ts
+function extractIpnFromFormData(formData) {
+  return {
+    result: String(formData.get("result") || ""),
+    checksum: String(formData.get("checksum") || "")
+  };
+}
+function extractIpnFromUrlEncoded(body) {
+  const params = new URLSearchParams(body);
+  return {
+    result: params.get("result") || "",
+    checksum: params.get("checksum") || ""
+  };
+}
+
+// src/core/ipn-processor.ts
+async function processIpn(payload, options) {
+  const { config, orderRepository, notifications } = options;
+  const verification = verifyChecksum(
+    payload.result,
+    payload.checksum,
+    config.checksumKey
+  );
+  if (!verification.valid || !verification.data) {
+    return {
+      success: false,
+      message: verification.error || "Invalid checksum",
+      statusCode: 403
+    };
+  }
+  const paymentInfo = verification.data;
+  const invoiceNo = paymentInfo.invoice_no;
+  const orderId = typeof invoiceNo === "string" && invoiceNo.trim().length > 0 ? invoiceNo : typeof invoiceNo === "number" ? String(invoiceNo) : null;
+  if (!orderId) {
+    return {
+      success: false,
+      message: "Missing invoice_no in IPN payload",
+      statusCode: 400
+    };
+  }
+  const isSuccess = Number(paymentInfo.status) === SUCCESS_STATUS;
+  const amount = Number(paymentInfo.amount ?? 0);
+  const currency = String(paymentInfo.currency ?? "");
+  if (isSuccess) {
+    try {
+      await orderRepository.updateOrderStatus(orderId, "completed");
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to update order: ${error instanceof Error ? error.message : String(error)}`,
+        statusCode: 500,
+        orderId
+      };
+    }
+    if (notifications?.onSuccess) {
+      try {
+        await notifications.onSuccess({
+          orderId,
+          status: "completed",
+          amount,
+          currency,
+          paymentMethod: "9pay",
+          metadata: paymentInfo
+        });
+      } catch {
+      }
+    }
+    return {
+      success: true,
+      message: "Order updated successfully",
+      statusCode: 200,
+      orderId
+    };
+  }
+  try {
+    await orderRepository.updateOrderStatus(orderId, "failed");
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to update order: ${error instanceof Error ? error.message : String(error)}`,
+      statusCode: 500,
+      orderId
+    };
+  }
+  if (notifications?.onFailure) {
+    try {
+      await notifications.onFailure({
+        orderId,
+        status: "failed",
+        amount,
+        currency,
+        paymentMethod: "9pay",
+        metadata: paymentInfo
+      });
+    } catch {
+    }
+  }
+  return {
+    success: false,
+    message: "Payment failed",
+    statusCode: 200,
+    orderId
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  NINEPAY_STATUS,
+  SUCCESS_STATUS,
+  buildHttpQuery,
+  buildSignature,
+  configFromEnv,
+  createPaymentUrl,
+  extractIpnFromFormData,
+  extractIpnFromUrlEncoded,
+  processIpn,
+  validateConfig,
+  verifyCallback,
+  verifyChecksum
+});