开放平台接入文档

接入总览

商户通过 OpenAPI 创建入金、出金订单，并查询汇率、余额与订单状态。生产请求必须同时通过商户状态、OpenAPI 权限、IP 白名单、RSA 请求加密、HMAC-SHA256 签名、5 分钟时间窗和一次性 nonce 校验。

上线前检查

1. 确认商户状态正常且 OpenAPI 权限已由管理员启用。
2. 在商户后台复制 UID；业务 JSON 和外层 envelope 的 merchantNo 必须都使用该 UID。
3. 配置所有调用服务器的固定出口 IPv4 或 IPv4 CIDR，禁止使用全网通配地址。
4. 配置可公网解析的回调 URL，并确保接收端不会重定向请求。
5. 安全保存请求加密公钥和仅显示一次的 HMAC signing secret；同步系统时间。
6. 回调接收端准备 eventId 唯一约束、验签逻辑，以及可选的回调解密私钥。

请求加密与签名

请求 canonical string 按以下顺序组成，使用 LF 换行且末尾没有换行。method 必须是大写 POST，path 只包含 URL pathname，不包含域名、query 或 fragment。

merchantNo=MCH-DEMO-1001
method=POST
path=/api/open/order/createBuyOrder
timestamp=1783737600000
nonce=dGVzdC1ub25jZS0wMDAx
encryptedData=BASE64_RSA_CIPHERTEXT

密钥管理

回调验签与解密

签名覆盖收到的 payload 原始对象语义：对象 key 递归按字典序排序、忽略值为 undefined 的对象字段、数组保持原顺序，并输出紧凑 JSON。必须先验签，再解密 payload。

{
  "eventId": "cb_1783737600000_abcd1234",
  "merchantNo": "MCH-DEMO-1001",
  "orderNo": "PI1783737600000ABC123",
  "timestamp": "1783737600000",
  "payload": {
    "encryption": "RSA_OAEP_SHA256_AES_256_GCM",
    "merchantNo": "MCH-DEMO-1001",
    "orderNo": "PI1783737600000ABC123",
    "encryptedKey": "BASE64_RSA_OAEP_SHA256_KEY",
    "iv": "BASE64_12_BYTE_IV",
    "tag": "BASE64_GCM_TAG",
    "encryptedData": "BASE64_AES_GCM_CIPHERTEXT",
    "encryptedAt": "2026-07-12T02:00:00.000Z"
  },
  "signature": "UNPADDED_BASE64URL_HMAC_SHA256"
}

回调 canonical string 同样使用 LF 且无末尾换行：

eventId=cb_1783737600000_abcd1234
merchantNo=MCH-DEMO-1001
orderNo=PI1783737600000ABC123
timestamp=1783737600000
payloadSha256=BASE64URL_SHA256_OF_STABLE_PAYLOAD_JSON

1. 1

   校验 eventId、merchantNo、orderNo、timestamp、payload、signature，并拒绝超过 5 分钟的回调。

2. 2

   计算 stable JSON payload SHA-256 和五行 canonical string，常量时间校验 HMAC signature。

3. 3

   在数据库事务中用唯一约束原子占用 eventId；重复 eventId 不得再次更新订单或资金。

4. 4

   payload.encryption 为 RSA_OAEP_SHA256_AES_256_GCM 时，用本地私钥解开 AES key，再用 AES-256-GCM 解密。

5. 5

   核对解密后 MerchantNo/OrderNo 与已认证外层字段一致，幂等推进本地业务状态。

6. 6

   成功后返回 HTTP 2xx，且 Body 为空、{"code":200}、{"success":true} 或纯文本 success；其他响应会进入重试。

幂等、重试与限流

全局错误码

SDK 与完整示例

const crypto = require("crypto");

const baseUrl = "https://pay.example.com";
const merchantNo = "MCH-DEMO-1001";
const signingSecret = process.env.CORRIDORPAY_SIGNING_SECRET;
const platformPublicKey = `-----BEGIN PUBLIC KEY-----
PASTE_PLATFORM_PUBLIC_KEY_HERE
-----END PUBLIC KEY-----`;

const payload = {
  merchantNo,
  amount: 1000,
  currencyType: "CNY",
  merchantOrderNo: "demo-001",
  customerName: "Alice",
  redirectUrl: "https://merchant.example.com/return",
  hideUsdt: false,
  paymentType: 1,
  callbackUrl: "https://merchant.example.com/callback",
  customerCountry: "CN",
  customerPhoneNumber: "13800000000",
  customerIdCardNumber: "110101199001010000"
};

function encryptPayload(data) {
  const key = crypto.createPublicKey(platformPublicKey);
  const blockSize = Math.floor((key.asymmetricKeyDetails?.modulusLength || 2048) / 8);
  const maxPayloadBlock = blockSize - 11;
  const input = Buffer.from(JSON.stringify(data), "utf8");
  const encryptedBlocks = [];

  for (let offset = 0; offset < input.length; offset += maxPayloadBlock) {
    encryptedBlocks.push(
      crypto.publicEncrypt(
        { key, padding: crypto.constants.RSA_PKCS1_PADDING },
        input.subarray(offset, offset + maxPayloadBlock)
      )
    );
  }

  return Buffer.concat(encryptedBlocks).toString("base64");
}

async function main() {
  const encryptedData = encryptPayload(payload);
  const timestamp = String(Date.now());
  const nonce = crypto.randomBytes(24).toString("base64url");
  const canonical = [
    `merchantNo=${merchantNo}`,
    "method=POST",
    "path=/api/open/order/createBuyOrder",
    `timestamp=${timestamp}`,
    `nonce=${nonce}`,
    `encryptedData=${encryptedData}`
  ].join("\n");
  const body = {
    merchantNo,
    timestamp,
    nonce,
    encryptedData,
    signature: crypto.createHmac("sha256", signingSecret).update(canonical, "utf8").digest("base64url")
  };

  const response = await fetch(baseUrl + "/api/open/order/createBuyOrder", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body)
  });

  console.log(response.status, await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

全部接口