9pay-integrate 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,195 @@
+/**
+ * Core type definitions for 9Pay integration.
+ * Framework-agnostic — no Next.js, React, or Express dependencies.
+ */
+interface NinePayConfig {
+    merchantKey: string;
+    secretKey: string;
+    checksumKey: string;
+    baseUrl?: string;
+    returnUrl: string;
+    cancelUrl?: string;
+}
+interface NinePayPaymentOptions {
+    /** 0: All, 1: Domestic, 2: International */
+    card_origin_allow?: 0 | 1 | 2;
+    /** Comma-separated: "VISA,MASTER,JCB,AMEX" */
+    card_brand_allow?: string;
+    /** Comma-separated BIN codes */
+    bin_allow?: string;
+    /** Card type filter */
+    card_type_allow?: string;
+    lang?: "en" | "vi";
+    method?: string;
+}
+interface CreatePaymentParams {
+    orderId: string | number;
+    amount: number;
+    currency: string;
+    description: string;
+    options?: NinePayPaymentOptions;
+}
+interface VerifyCallbackResult {
+    success: boolean;
+    orderId?: string;
+    amount?: number;
+    currency?: string;
+    status?: number;
+    /** Raw decoded payload for consumer access */
+    rawParams: Record<string, unknown>;
+    error?: string;
+}
+interface VerificationResult<T = Record<string, unknown>> {
+    valid: boolean;
+    data: T | null;
+    error?: string;
+}
+type OrderStatus = "neworder" | "pending" | "completed" | "failed";
+interface CreateOrderParams {
+    orderId?: string;
+    totalAmount: number;
+    currency: string;
+    paymentMethod: string;
+    metadata?: Record<string, unknown>;
+}
+interface OrderRepository<TOrder = unknown> {
+    createOrder(params: CreateOrderParams): Promise<TOrder>;
+    getOrderStatus(orderId: string): Promise<OrderStatus | null>;
+    updateOrderStatus(orderId: string, status: "completed" | "failed"): Promise<TOrder | null>;
+}
+interface NotificationContext {
+    orderId: string;
+    status: "completed" | "failed";
+    amount: number;
+    currency: string;
+    paymentMethod: string;
+    metadata?: Record<string, unknown>;
+}
+type NotificationHandler = (ctx: NotificationContext) => Promise<void> | void;
+interface NotificationHooks {
+    onSuccess?: NotificationHandler;
+    onFailure?: NotificationHandler;
+}
+interface IpnRawPayload {
+    result: string;
+    checksum: string;
+}
+interface IpnProcessResult {
+    success: boolean;
+    message: string;
+    statusCode: number;
+    orderId?: string;
+}
+interface IpnProcessorOptions {
+    config: NinePayConfig;
+    orderRepository: OrderRepository;
+    notifications?: NotificationHooks;
+}
+interface PaymentStatusResponse {
+    success: boolean;
+    status: OrderStatus | null;
+    message?: string;
+}
+
+/**
+ * Validate and normalize a partial NinePayConfig.
+ * Throws if required fields are missing — fail fast at init time.
+ */
+declare function validateConfig(config: Partial<NinePayConfig>): NinePayConfig;
+/**
+ * Build NinePayConfig from any environment-like object.
+ * Accepts Record<string, string | undefined> so it works with
+ * process.env, Vercel env, or custom config loaders.
+ */
+declare function configFromEnv(env: Record<string, string | undefined>): NinePayConfig;
+
+/**
+ * Create a signed 9Pay payment redirect URL.
+ *
+ * The user is redirected to this URL to complete payment on 9Pay's portal.
+ * After payment, 9Pay redirects the browser to config.returnUrl (callback)
+ * and sends a server-to-server POST to config.returnUrl (IPN).
+ */
+declare function createPaymentUrl(config: NinePayConfig, params: CreatePaymentParams): string;
+
+/**
+ * Build sorted HTTP query string from key-value pairs.
+ * Keys are sorted alphabetically — required by 9Pay for valid signatures.
+ */
+declare function buildHttpQuery(data: Record<string, string | number>): string;
+/**
+ * Build HMAC-SHA256 signature for 9Pay payment creation request.
+ * Message format: POST\n{baseUrl}/payments/create\n{time}\n{httpQuery}
+ * Returns Base64-encoded signature.
+ */
+declare function buildSignature(baseUrl: string, time: number, httpQuery: string, secretKey: string): string;
+
+/**
+ * Verify 9Pay callback/IPN checksum.
+ *
+ * 9Pay computes: SHA256(result + checksumKey).toUpperCase()
+ * We recompute and compare. If valid, decode result from base64 → JSON.
+ *
+ * @param result Base64-encoded JSON payload from 9Pay
+ * @param checksum SHA256 hex hash from 9Pay
+ * @param checksumKey Shared secret key
+ */
+declare function verifyChecksum(result: string, checksum: string, checksumKey: string): VerificationResult;
+
+/**
+ * Verify 9Pay browser redirect callback.
+ *
+ * Takes URL search params (from GET /api/checkout/9pay/callback),
+ * verifies the checksum, extracts orderId and payment info.
+ *
+ * Returns an object — consumer decides what to redirect to.
+ * This is Option B: package does NOT redirect, only returns data.
+ */
+declare function verifyCallback(searchParams: URLSearchParams, config: NinePayConfig): VerifyCallbackResult;
+
+/**
+ * Extract IPN payload from FormData.
+ * 9Pay sends POST with result and checksum fields.
+ */
+declare function extractIpnFromFormData(formData: FormData): IpnRawPayload;
+/**
+ * Extract IPN payload from URL-encoded string body.
+ * 9Pay may send application/x-www-form-urlencoded instead of FormData.
+ */
+declare function extractIpnFromUrlEncoded(body: string): IpnRawPayload;
+
+/**
+ * Process a 9Pay IPN (Instant Payment Notification) — adapter-agnostic.
+ *
+ * This is the core IPN logic, completely independent of Next.js, Express,
+ * or any framework. It:
+ *  1. Verifies the checksum
+ *  2. Decodes the payment info
+ *  3. Extracts the orderId (invoice_no)
+ *  4. Checks payment status (5 = success)
+ *  5. Calls orderRepository.updateOrderStatus()
+ *  6. Calls notification hooks (onSuccess / onFailure)
+ *
+ * The Next.js adapter (or Express, Hono, etc.) is responsible for:
+ *  - Parsing the incoming request into IpnRawPayload
+ *  - Returning the appropriate HTTP response
+ */
+declare function processIpn(payload: IpnRawPayload, options: IpnProcessorOptions): Promise<IpnProcessResult>;
+
+/**
+ * 9Pay status codes and defaults.
+ */
+declare const NINEPAY_STATUS: {
+    readonly PENDING: 1;
+    readonly PROCESSING: 2;
+    readonly CANCELLED: 3;
+    readonly REFUNDED: 4;
+    readonly SUCCESS: 5;
+    readonly FAILED: 6;
+};
+/** Status code indicating successful payment */
+declare const SUCCESS_STATUS: 5;
+/** Default 9Pay base URL */
+declare const DEFAULT_BASE_URL = "https://payment.9pay.vn";
+
+export { type CreateOrderParams, type CreatePaymentParams, DEFAULT_BASE_URL, type IpnProcessResult, type IpnProcessorOptions, type IpnRawPayload, NINEPAY_STATUS, type NinePayConfig, type NinePayPaymentOptions, type NotificationContext, type NotificationHandler, type NotificationHooks, type OrderRepository, type OrderStatus, type PaymentStatusResponse, SUCCESS_STATUS, type VerificationResult, type VerifyCallbackResult, buildHttpQuery, buildSignature, configFromEnv, createPaymentUrl, extractIpnFromFormData, extractIpnFromUrlEncoded, processIpn, validateConfig, verifyCallback, verifyChecksum };

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Core type definitions for 9Pay integration.
+ * Framework-agnostic — no Next.js, React, or Express dependencies.
+ */
+interface NinePayConfig {
+    merchantKey: string;
+    secretKey: string;
+    checksumKey: string;
+    baseUrl?: string;
+    returnUrl: string;
+    cancelUrl?: string;
+}
+interface NinePayPaymentOptions {
+    /** 0: All, 1: Domestic, 2: International */
+    card_origin_allow?: 0 | 1 | 2;
+    /** Comma-separated: "VISA,MASTER,JCB,AMEX" */
+    card_brand_allow?: string;
+    /** Comma-separated BIN codes */
+    bin_allow?: string;
+    /** Card type filter */
+    card_type_allow?: string;
+    lang?: "en" | "vi";
+    method?: string;
+}
+interface CreatePaymentParams {
+    orderId: string | number;
+    amount: number;
+    currency: string;
+    description: string;
+    options?: NinePayPaymentOptions;
+}
+interface VerifyCallbackResult {
+    success: boolean;
+    orderId?: string;
+    amount?: number;
+    currency?: string;
+    status?: number;
+    /** Raw decoded payload for consumer access */
+    rawParams: Record<string, unknown>;
+    error?: string;
+}
+interface VerificationResult<T = Record<string, unknown>> {
+    valid: boolean;
+    data: T | null;
+    error?: string;
+}
+type OrderStatus = "neworder" | "pending" | "completed" | "failed";
+interface CreateOrderParams {
+    orderId?: string;
+    totalAmount: number;
+    currency: string;
+    paymentMethod: string;
+    metadata?: Record<string, unknown>;
+}
+interface OrderRepository<TOrder = unknown> {
+    createOrder(params: CreateOrderParams): Promise<TOrder>;
+    getOrderStatus(orderId: string): Promise<OrderStatus | null>;
+    updateOrderStatus(orderId: string, status: "completed" | "failed"): Promise<TOrder | null>;
+}
+interface NotificationContext {
+    orderId: string;
+    status: "completed" | "failed";
+    amount: number;
+    currency: string;
+    paymentMethod: string;
+    metadata?: Record<string, unknown>;
+}
+type NotificationHandler = (ctx: NotificationContext) => Promise<void> | void;
+interface NotificationHooks {
+    onSuccess?: NotificationHandler;
+    onFailure?: NotificationHandler;
+}
+interface IpnRawPayload {
+    result: string;
+    checksum: string;
+}
+interface IpnProcessResult {
+    success: boolean;
+    message: string;
+    statusCode: number;
+    orderId?: string;
+}
+interface IpnProcessorOptions {
+    config: NinePayConfig;
+    orderRepository: OrderRepository;
+    notifications?: NotificationHooks;
+}
+interface PaymentStatusResponse {
+    success: boolean;
+    status: OrderStatus | null;
+    message?: string;
+}
+
+/**
+ * Validate and normalize a partial NinePayConfig.
+ * Throws if required fields are missing — fail fast at init time.
+ */
+declare function validateConfig(config: Partial<NinePayConfig>): NinePayConfig;
+/**
+ * Build NinePayConfig from any environment-like object.
+ * Accepts Record<string, string | undefined> so it works with
+ * process.env, Vercel env, or custom config loaders.
+ */
+declare function configFromEnv(env: Record<string, string | undefined>): NinePayConfig;
+
+/**
+ * Create a signed 9Pay payment redirect URL.
+ *
+ * The user is redirected to this URL to complete payment on 9Pay's portal.
+ * After payment, 9Pay redirects the browser to config.returnUrl (callback)
+ * and sends a server-to-server POST to config.returnUrl (IPN).
+ */
+declare function createPaymentUrl(config: NinePayConfig, params: CreatePaymentParams): string;
+
+/**
+ * Build sorted HTTP query string from key-value pairs.
+ * Keys are sorted alphabetically — required by 9Pay for valid signatures.
+ */
+declare function buildHttpQuery(data: Record<string, string | number>): string;
+/**
+ * Build HMAC-SHA256 signature for 9Pay payment creation request.
+ * Message format: POST\n{baseUrl}/payments/create\n{time}\n{httpQuery}
+ * Returns Base64-encoded signature.
+ */
+declare function buildSignature(baseUrl: string, time: number, httpQuery: string, secretKey: string): string;
+
+/**
+ * Verify 9Pay callback/IPN checksum.
+ *
+ * 9Pay computes: SHA256(result + checksumKey).toUpperCase()
+ * We recompute and compare. If valid, decode result from base64 → JSON.
+ *
+ * @param result Base64-encoded JSON payload from 9Pay
+ * @param checksum SHA256 hex hash from 9Pay
+ * @param checksumKey Shared secret key
+ */
+declare function verifyChecksum(result: string, checksum: string, checksumKey: string): VerificationResult;
+
+/**
+ * Verify 9Pay browser redirect callback.
+ *
+ * Takes URL search params (from GET /api/checkout/9pay/callback),
+ * verifies the checksum, extracts orderId and payment info.
+ *
+ * Returns an object — consumer decides what to redirect to.
+ * This is Option B: package does NOT redirect, only returns data.
+ */
+declare function verifyCallback(searchParams: URLSearchParams, config: NinePayConfig): VerifyCallbackResult;
+
+/**
+ * Extract IPN payload from FormData.
+ * 9Pay sends POST with result and checksum fields.
+ */
+declare function extractIpnFromFormData(formData: FormData): IpnRawPayload;
+/**
+ * Extract IPN payload from URL-encoded string body.
+ * 9Pay may send application/x-www-form-urlencoded instead of FormData.
+ */
+declare function extractIpnFromUrlEncoded(body: string): IpnRawPayload;
+
+/**
+ * Process a 9Pay IPN (Instant Payment Notification) — adapter-agnostic.
+ *
+ * This is the core IPN logic, completely independent of Next.js, Express,
+ * or any framework. It:
+ *  1. Verifies the checksum
+ *  2. Decodes the payment info
+ *  3. Extracts the orderId (invoice_no)
+ *  4. Checks payment status (5 = success)
+ *  5. Calls orderRepository.updateOrderStatus()
+ *  6. Calls notification hooks (onSuccess / onFailure)
+ *
+ * The Next.js adapter (or Express, Hono, etc.) is responsible for:
+ *  - Parsing the incoming request into IpnRawPayload
+ *  - Returning the appropriate HTTP response
+ */
+declare function processIpn(payload: IpnRawPayload, options: IpnProcessorOptions): Promise<IpnProcessResult>;
+
+/**
+ * 9Pay status codes and defaults.
+ */
+declare const NINEPAY_STATUS: {
+    readonly PENDING: 1;
+    readonly PROCESSING: 2;
+    readonly CANCELLED: 3;
+    readonly REFUNDED: 4;
+    readonly SUCCESS: 5;
+    readonly FAILED: 6;
+};
+/** Status code indicating successful payment */
+declare const SUCCESS_STATUS: 5;
+/** Default 9Pay base URL */
+declare const DEFAULT_BASE_URL = "https://payment.9pay.vn";
+
+export { type CreateOrderParams, type CreatePaymentParams, DEFAULT_BASE_URL, type IpnProcessResult, type IpnProcessorOptions, type IpnRawPayload, NINEPAY_STATUS, type NinePayConfig, type NinePayPaymentOptions, type NotificationContext, type NotificationHandler, type NotificationHooks, type OrderRepository, type OrderStatus, type PaymentStatusResponse, SUCCESS_STATUS, type VerificationResult, type VerifyCallbackResult, buildHttpQuery, buildSignature, configFromEnv, createPaymentUrl, extractIpnFromFormData, extractIpnFromUrlEncoded, processIpn, validateConfig, verifyCallback, verifyChecksum };

package/dist/index.js

@@ -0,0 +1,268 @@
+// 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
+import * as crypto from "crypto";
+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
+import * as crypto2 from "crypto";
+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
+  };
+}
+export {
+  DEFAULT_BASE_URL,
+  NINEPAY_STATUS,
+  SUCCESS_STATUS,
+  buildHttpQuery,
+  buildSignature,
+  configFromEnv,
+  createPaymentUrl,
+  extractIpnFromFormData,
+  extractIpnFromUrlEncoded,
+  processIpn,
+  validateConfig,
+  verifyCallback,
+  verifyChecksum
+};