ipaynow-nodejs-sdk 1.0.0

package/README.md

@@ -0,0 +1,205 @@
+# iPayNow Node.js SDK
+
+现在支付 Node.js SDK，封装统一下单、订单查询、退款、撤销、回调验签和前端表单提交字段生成。基于原生 ESM 编写，运行时依赖仅使用 Node.js 内置模块（`node:crypto`）与全局 `fetch`。
+
+## 环境要求
+
+- Node.js 18+（需要全局 `fetch`、`AbortSignal.timeout` 与 `node:test`，建议使用 20+）
+- 本包为 ESM（`package.json` 中 `"type": "module"`），只能使用 `import` 语法引入，不支持 `require`
+
+## 安装
+
+```bash
+npm install ipaynow-nodejs-sdk
+```
+
+## 快速开始
+
+以 H5 统一下单为例：
+
+```javascript
+import {
+  IpaynowClient,
+  IpaynowConfig,
+  H5UnifiedOrderParams,
+  H5UnifiedOrderRequest,
+} from "ipaynow-nodejs-sdk";
+
+const config = new IpaynowConfig({
+  appId: "appId",
+  appKey: "appKey",
+  baseUrl: "https://pay.ipaynow.cn",
+});
+const client = new IpaynowClient(config);
+
+const params = new H5UnifiedOrderParams({
+  mhtOrderNo: "ORDER202607030001",
+  mhtOrderName: "测试订单",
+  mhtOrderDetail: "测试订单",
+  mhtOrderAmt: 1,
+  mhtOrderTimeOut: 120,
+  mhtOrderStartTime: "20260703120000",
+  notifyUrl: "https://example.com/notify",
+  frontNotifyUrl: "https://example.com/front",
+  payChannelType: "12",
+  outputType: "1",
+  consumerCreateIp: "127.0.0.1",
+});
+
+const response = await client.execute(new H5UnifiedOrderRequest(params));
+if (response.isSuccess()) {
+  const tn = response.tn();
+  console.log(tn);
+}
+```
+
+`Params` 构造函数也接受普通对象字面量（不强制先 `new`），`Request` 构造函数会在收到普通对象时自动包装为对应的 `Params` 实例：
+
+```javascript
+const response = await client.execute(
+  new H5UnifiedOrderRequest({ mhtOrderNo: "ORDER202607030001", mhtOrderAmt: 1 })
+);
+```
+
+## 前端 Form 表单提交
+
+需要让浏览器直接向现在支付网关提交表单时，使用 `buildFormFields` 生成完整请求字段。入参与 `execute` 一致，SDK 不发起 HTTP 请求：
+
+```javascript
+const fields = client.buildFormFields(new H5UnifiedOrderRequest(params));
+```
+
+返回字段包含业务参数、公共参数和签名字段，例如：
+
+- `funcode`
+- `version`
+- `appId`
+- `mhtCharset`
+- `mhtSignType` 或 `signType`
+- `mhtSignature`
+
+表单提交地址由请求路径决定：
+
+```javascript
+const request = new H5UnifiedOrderRequest(params);
+const action = config.endpoint(request.path);
+```
+
+## 支持接口
+
+| funcode | 操作 | Params | Request | Response |
+| --- | --- | --- | --- | --- |
+| `WP001` (v1.0.0) | JSAPI 统一下单 | `JsapiUnifiedOrderParams` | `JsapiUnifiedOrderRequest` | `JsapiUnifiedOrderResponse` |
+| `WP001` (v1.0.3) | 聚合码统一下单 | `AggregateCodeUnifiedOrderParams` | `AggregateCodeUnifiedOrderRequest` | `AggregateCodeUnifiedOrderResponse` |
+| `WP001` (v1.0.0) | 小程序统一下单 | `MiniProgramUnifiedOrderParams` | `MiniProgramUnifiedOrderRequest` | `MiniProgramUnifiedOrderResponse` |
+| `WP001` (v1.0.0) | H5 统一下单 | `H5UnifiedOrderParams` | `H5UnifiedOrderRequest` | `H5UnifiedOrderResponse` |
+| `WP001` (v1.0.3) | APP 统一下单 | `AppUnifiedOrderParams` | `AppUnifiedOrderRequest` | `AppUnifiedOrderResponse` |
+| `MQ002` | 订单查询 | `OrderQueryParams` | `OrderQueryRequest` | `OrderQueryResponse` |
+| `R001` | 退款 | `RefundParams` | `RefundRequest` | `RefundResponse` |
+| `Q001` | 退款查询 | `RefundQueryParams` | `RefundQueryRequest` | `RefundQueryResponse` |
+| `R002` | 撤销 | `ReverseParams` | `ReverseRequest` | `ReverseResponse` |
+| `Q002` | 撤销查询 | `ReverseQueryParams` | `ReverseQueryRequest` | `ReverseQueryResponse` |
+| `N001` | 支付结果回调 | - | - | `PaymentNotifyResponse`（经 `NotifyParser.parsePayment`） |
+| `RN001` | 退款结果回调 | - | - | `RefundNotifyResponse`（经 `NotifyParser.parseRefund`） |
+
+统一下单、订单查询走网关根路径 `/`；退款、退款查询走 `/refund/refundOrder`；撤销、撤销查询走 `/refund/cancelOrder`（撤销查询实际路径为 `/refund/refundOrder`，与源码一致）。所有 `Request` 构造函数第二个参数均可传入版本号字符串或 `{ version }` 覆盖默认版本，例如 `new OrderQueryRequest(params, "1.0.1")`。
+
+## 响应判断
+
+`isSuccess()` 按操作类型使用不同判定字段（见 `src/responses.js` 真实实现）：
+
+- 统一下单族（JSAPI/聚合码/小程序/H5/APP）：`responseCode === "A001"`（继承自 `IpaynowResponse`）。
+- 订单查询：同样使用 `responseCode === "A001"`。
+- 退款、退款查询、撤销、撤销查询：`responseCode === "R000"`。
+- 支付结果回调（`PaymentNotifyResponse`）：`transStatus === "A001"`。
+- 退款结果回调（`RefundNotifyResponse`）：`tradeStatus === "A001"`。
+
+统一下单响应额外提供便捷访问器：
+
+```javascript
+response.tn();            // 支付要素，兼容大写字段 TN
+response.nowPayOrderNo();  // 现在支付流水号
+```
+
+订单查询响应提供：`response.transStatus()`、`response.nowPayOrderNo()`、`response.payTime()`、`response.channelOrderNo()`。
+
+也可以直接读取原始字段：
+
+```javascript
+const code = response.code();       // responseCode
+const message = response.message(); // responseMsg
+const rawBody = response.rawBody(); // 原始报文串
+const fields = response.fields();   // 全部字段的副本
+```
+
+## 扩展字段
+
+`Params` 构造函数支持 `extraParams`（普通对象），用于传递 SDK 尚未显式建模的业务字段：
+
+```javascript
+const params = new H5UnifiedOrderParams({
+  mhtOrderNo: "ORDER202607030001",
+  mhtOrderAmt: 1,
+  extraParams: { mhtGoodsTag: "TAG001" },
+});
+```
+
+`extraParams` 中的字段与命名字段合并时，`extraParams` 后写覆盖前写（与已建模字段同名时以 `extraParams` 为准）。SDK 只在客户端组装阶段（`IpaynowClient#signedFields`）以固定顺序追加公共字段和签名字段，因此业务参数无法覆盖以下保留字段：
+
+- `funcode`
+- `version`
+- `appId`
+- `mhtCharset`
+- `mhtSignType`
+- `signType`
+- `mhtSignature`
+- `signature`
+
+## 回调验签
+
+```javascript
+import { NotifyParser, NotifyAck } from "ipaynow-nodejs-sdk";
+
+const notify = NotifyParser.parsePayment(requestBody, appKey);
+if (notify.isSuccess()) {
+  // 处理支付成功业务逻辑
+}
+// 按现在支付协议要求同步返回 success=Y / success=N
+const ackBody = NotifyAck.success(); // 或 NotifyAck.fail()
+```
+
+退款回调：
+
+```javascript
+const notify = NotifyParser.parseRefund(requestBody, appKey);
+```
+
+两者验签失败均抛出 `IpaynowError`（`codeName: "SIGN_ERROR"`）。
+
+## 错误处理
+
+SDK 只抛出一种异常类型 `IpaynowError`，通过 `code` / `codeName` 属性区分具体失败原因：
+
+```javascript
+import { IpaynowError } from "ipaynow-nodejs-sdk";
+
+try {
+  await client.execute(request);
+} catch (err) {
+  if (err instanceof IpaynowError) {
+    console.error(err.codeName, err.code, err.message);
+  }
+}
+```
+
+错误码表（`src/errors.js`）：
+
+| codeName | code | 默认信息 |
+| --- | --- | --- |
+| `SYSTEM_ERROR` | `E0001` | 组件内部异常 |
+| `HTTP_EXCEPTION` | `E0002` | HTTP异常 |
+| `CONNECT_TIMEOUT` | `E0003` | ConnectTimeOut |
+| `SOCKET_TIMEOUT` | `E0004` | SocketTimeOut |
+| `SIGN_ERROR` | `E0012` | 渠道报文验签失败 |
+
+注意：默认传输基于全局 `fetch`，无法区分“建连超时”与“读取超时”，超时统一映射为 `SOCKET_TIMEOUT`；`connectTimeoutMillis + readTimeoutMillis` 之和作为整体请求超时预算传给 `AbortSignal.timeout`。

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ipaynow-nodejs-sdk",
+  "version": "1.0.0",
+  "description": "现在支付（iPayNow）Node.js SDK：统一下单、订单查询、退款、撤销、回调验签。",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "author": "iPayNow",
+  "license": "UNLICENSED",
+  "homepage": "https://www.ipaynow.cn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipaynow/ipaynow-sdk.git",
+    "directory": "ipaynow-nodejs-sdk"
+  }
+}

package/src/client.js

@@ -0,0 +1,106 @@
+import { sign, verify, clean } from "./signer.js";
+import { parseResponse } from "./form.js";
+import { IpaynowError } from "./errors.js";
+
+/**
+ * 基于全局 fetch 的默认传输实现。
+ * fetch 无法区分“建连超时”与“读取超时”（AbortError/TimeoutError 一概抛出），
+ * 因此超时统一映射为 SOCKET_TIMEOUT，并在注释中说明这一限制。
+ * @param {import("./config.js").IpaynowConfig} config
+ * @returns {(url: string, params: Record<string, string>) => Promise<string>}
+ */
+function createFetchTransport(config) {
+  return async function transport(url, params) {
+    const body = new URLSearchParams(params);
+    const funcode = params.funcode;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body,
+        // fetch 没有独立的建连/读取超时旋钮，用两者之和近似整体请求预算。
+        signal: AbortSignal.timeout(config.connectTimeoutMillis + config.readTimeoutMillis),
+      });
+    } catch (err) {
+      if (err.name === "TimeoutError" || err.name === "AbortError") {
+        throw new IpaynowError("SOCKET_TIMEOUT", `现在支付请求超时，功能码=${funcode}`, { cause: err });
+      }
+      throw new IpaynowError("HTTP_EXCEPTION", `现在支付请求异常，功能码=${funcode}`, { cause: err });
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new IpaynowError(
+        "HTTP_EXCEPTION",
+        `现在支付HTTP请求失败，状态码=${response.status}，功能码=${funcode}，响应报文=${text}`
+      );
+    }
+    return text;
+  };
+}
+
+/**
+ * iPayNow 客户端：组装公共字段 → 签名 → POST 表单 → 解析响应 → 验签 → 返回类型化 Response。
+ */
+export class IpaynowClient {
+  /**
+   * @param {import("./config.js").IpaynowConfig} config
+   * @param {(url: string, params: Record<string, string>) => Promise<string>} [transport] 可注入的传输实现，便于测试
+   */
+  constructor(config, transport) {
+    this.config = config;
+    this.transport = transport ?? createFetchTransport(config);
+  }
+
+  /**
+   * @param {import("./requests.js").IpaynowRequest} request
+   * @returns {Promise<import("./responses.js").IpaynowResponse>}
+   */
+  async execute(request) {
+    const funcode = request.funcode;
+    const fields = this.signedFields(request);
+
+    const responseText = await this.transport(this.config.endpoint(request.path), fields);
+    const responseFields = parseResponse(responseText);
+
+    if (!verify(responseFields, this.config, request.responseSignatureField, request.excludeSignType)) {
+      throw new IpaynowError("SIGN_ERROR", `现在支付响应验签失败，功能码=${funcode}`);
+    }
+
+    const response = new request.responseClass();
+    response.load(responseFields, responseText);
+    return response;
+  }
+
+  /**
+   * 返回签名后的完整表单字段（供前端跳转表单场景），不发请求。
+   * @param {import("./requests.js").IpaynowRequest} request
+   * @returns {Record<string, string>}
+   */
+  buildFormFields(request) {
+    return this.signedFields(request);
+  }
+
+  /**
+   * @param {import("./requests.js").IpaynowRequest} request
+   * @returns {Record<string, string>}
+   */
+  signedFields(request) {
+    const fields = {
+      ...request.toFields(),
+      funcode: request.funcode,
+      version: request.version,
+      appId: this.config.appId,
+      mhtCharset: request.mhtCharset,
+    };
+    fields[request.signTypeField] = this.config.signType;
+    fields[request.signatureField] = sign(
+      fields,
+      this.config,
+      request.excludeSignType,
+      request.signatureField,
+      request.responseSignatureField
+    );
+    return clean(fields);
+  }
+}

package/src/config.js

@@ -0,0 +1,87 @@
+import crypto from "node:crypto";
+
+function requireNonBlank(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${name} 不能为空`);
+  }
+  return value;
+}
+
+export const SignType = Object.freeze({
+  MD5: "MD5",
+  RSA: "RSA",
+});
+
+function decodeBase64(value, name) {
+  if (value.includes("-----BEGIN") || value.includes("-----END")) {
+    throw new TypeError(`${name} 仅支持裸 base64，不支持 PEM`);
+  }
+  try {
+    return Buffer.from(value.replace(/\s+/g, ""), "base64");
+  } catch (error) {
+    throw new TypeError(`${name} 非法，需传裸 base64`, { cause: error });
+  }
+}
+
+/**
+ * iPayNow SDK 配置：appId / appKey / baseUrl / 超时时间。
+ */
+export class IpaynowConfig {
+  /**
+   * @param {{appId: string, appKey?: string, signType?: string, mchPrivateKey?: string, ipaynowPublicKey?: string, baseUrl?: string, connectTimeoutMillis?: number, readTimeoutMillis?: number}} options
+   */
+  constructor({
+    appId,
+    appKey,
+    signType = SignType.MD5,
+    mchPrivateKey,
+    ipaynowPublicKey,
+    baseUrl = "https://pay.ipaynow.cn",
+    connectTimeoutMillis = 5000,
+    readTimeoutMillis = 15000,
+  } = {}) {
+    this.appId = requireNonBlank(appId, "appId");
+    this.signType = signType ?? SignType.MD5;
+    if (this.signType === SignType.MD5) {
+      this.appKey = requireNonBlank(appKey, "appKey");
+      this.mchPrivateKey = null;
+      this.ipaynowPublicKey = null;
+      this.mchPrivateKeyObject = null;
+      this.ipaynowPublicKeyObject = null;
+    } else if (this.signType === SignType.RSA) {
+      this.appKey = null;
+      this.mchPrivateKey = requireNonBlank(mchPrivateKey, "mchPrivateKey");
+      this.ipaynowPublicKey = requireNonBlank(ipaynowPublicKey, "ipaynowPublicKey");
+      this.mchPrivateKeyObject = crypto.createPrivateKey({
+        key: decodeBase64(this.mchPrivateKey, "mchPrivateKey"),
+        type: "pkcs8",
+        format: "der",
+      });
+      this.ipaynowPublicKeyObject = crypto.createPublicKey({
+        key: decodeBase64(this.ipaynowPublicKey, "ipaynowPublicKey"),
+        type: "spki",
+        format: "der",
+      });
+    } else {
+      throw new TypeError(`不支持的签名类型: ${this.signType}`);
+    }
+    requireNonBlank(baseUrl, "baseUrl");
+    if (!(connectTimeoutMillis > 0) || !(readTimeoutMillis > 0)) {
+      throw new TypeError(
+        `超时时间必须大于 0：connectTimeoutMillis=${connectTimeoutMillis}，readTimeoutMillis=${readTimeoutMillis}`
+      );
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.connectTimeoutMillis = connectTimeoutMillis;
+    this.readTimeoutMillis = readTimeoutMillis;
+  }
+
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
+  endpoint(path) {
+    const normalizedPath = !path ? "/" : path.startsWith("/") ? path : `/${path}`;
+    return `${this.baseUrl}${normalizedPath}`;
+  }
+}

package/src/errors.js

@@ -0,0 +1,36 @@
+/**
+ * iPayNow SDK 统一错误码。调用方只捕获 IpaynowError 一种异常类型，
+ * 通过 `code`/`codeName` 属性区分具体失败原因。
+ */
+export const IpaynowErrorCode = Object.freeze({
+  SYSTEM_ERROR: "E0001",
+  HTTP_EXCEPTION: "E0002",
+  CONNECT_TIMEOUT: "E0003",
+  SOCKET_TIMEOUT: "E0004",
+  SIGN_ERROR: "E0012",
+});
+
+const DEFAULT_MESSAGES = Object.freeze({
+  SYSTEM_ERROR: "组件内部异常",
+  HTTP_EXCEPTION: "HTTP异常",
+  CONNECT_TIMEOUT: "ConnectTimeOut",
+  SOCKET_TIMEOUT: "SocketTimeOut",
+  SIGN_ERROR: "渠道报文验签失败",
+});
+
+/**
+ * iPayNow SDK 统一异常。
+ */
+export class IpaynowError extends Error {
+  /**
+   * @param {keyof typeof IpaynowErrorCode} codeName
+   * @param {string} [message]
+   * @param {{cause?: unknown}} [options]
+   */
+  constructor(codeName, message, options) {
+    super(message ?? DEFAULT_MESSAGES[codeName], options);
+    this.name = "IpaynowError";
+    this.codeName = codeName;
+    this.code = IpaynowErrorCode[codeName];
+  }
+}

package/src/form.js

@@ -0,0 +1,14 @@
+/**
+ * 解析 `k=v&k2=v2` 表单串为字段表（值已 URL-decode）。
+ * @param {string} text
+ * @returns {Record<string, string>}
+ */
+export function parseResponse(text) {
+  const trimmed = typeof text === "string" ? text.trim() : "";
+  if (!trimmed) return {};
+  const out = {};
+  for (const [key, value] of new URLSearchParams(trimmed)) {
+    out[key] = value;
+  }
+  return out;
+}

package/src/index.js

@@ -0,0 +1,50 @@
+export { IpaynowError, IpaynowErrorCode } from "./errors.js";
+export { IpaynowConfig, SignType } from "./config.js";
+export { sign, verify, clean, md5Hex } from "./signer.js";
+export { parseResponse } from "./form.js";
+export { IpaynowClient } from "./client.js";
+export { NotifyParser, NotifyAck } from "./notify.js";
+
+export {
+  JsapiUnifiedOrderParams,
+  AggregateCodeUnifiedOrderParams,
+  MiniProgramUnifiedOrderParams,
+  H5UnifiedOrderParams,
+  AppUnifiedOrderParams,
+  OrderQueryParams,
+  RefundParams,
+  RefundQueryParams,
+  ReverseParams,
+  ReverseQueryParams,
+} from "./params.js";
+
+export {
+  IpaynowRequest,
+  JsapiUnifiedOrderRequest,
+  AggregateCodeUnifiedOrderRequest,
+  MiniProgramUnifiedOrderRequest,
+  H5UnifiedOrderRequest,
+  AppUnifiedOrderRequest,
+  OrderQueryRequest,
+  RefundRequest,
+  RefundQueryRequest,
+  ReverseRequest,
+  ReverseQueryRequest,
+} from "./requests.js";
+
+export {
+  IpaynowResponse,
+  UnifiedOrderResponse,
+  JsapiUnifiedOrderResponse,
+  AggregateCodeUnifiedOrderResponse,
+  MiniProgramUnifiedOrderResponse,
+  H5UnifiedOrderResponse,
+  AppUnifiedOrderResponse,
+  OrderQueryResponse,
+  RefundResponse,
+  RefundQueryResponse,
+  ReverseResponse,
+  ReverseQueryResponse,
+  PaymentNotifyResponse,
+  RefundNotifyResponse,
+} from "./responses.js";

package/src/notify.js

@@ -0,0 +1,52 @@
+import { parseResponse } from "./form.js";
+import { verify } from "./signer.js";
+import { IpaynowError } from "./errors.js";
+import { PaymentNotifyResponse, RefundNotifyResponse } from "./responses.js";
+
+/**
+ * @param {string} body
+ * @param {import("./config.js").IpaynowConfig} config
+ * @param {boolean} excludeSignType
+ * @param {new () => import("./responses.js").IpaynowResponse} ResponseClass
+ */
+function parse(body, config, excludeSignType, ResponseClass) {
+  const fields = parseResponse(body);
+  if (!verify(fields, config, "signature", excludeSignType)) {
+    throw new IpaynowError("SIGN_ERROR", "现在支付回调通知验签失败");
+  }
+  const response = new ResponseClass();
+  response.load(fields, body);
+  return response;
+}
+
+export const NotifyParser = Object.freeze({
+  /**
+   * N001 支付回调，signType 参与签名。
+   * @param {string} body
+   * @param {import("./config.js").IpaynowConfig} config
+   * @returns {PaymentNotifyResponse}
+   */
+  parsePayment(body, config) {
+    return parse(body, config, false, PaymentNotifyResponse);
+  },
+
+  /**
+   * RN001 退款回调，signType 不参与签名。
+   * @param {string} body
+   * @param {import("./config.js").IpaynowConfig} config
+   * @returns {RefundNotifyResponse}
+   */
+  parseRefund(body, config) {
+    return parse(body, config, true, RefundNotifyResponse);
+  },
+});
+
+/** 回调同步应答体 */
+export const NotifyAck = Object.freeze({
+  success() {
+    return "success=Y";
+  },
+  fail() {
+    return "success=N";
+  },
+});