聚合支付接口文档

1. 接入准备

上线前，商户管理员在商户系统的“应用管理”中创建应用。每个商户最多创建 20 个应用，建议按环境和业务系统隔离，例如“商城生产环境”“ERP 测试环境”。

• appId：由本系统自动生成并保存在本系统，用于标识调用应用。
• apiSecret：创建应用时自动生成的请求签名密钥。
• 回调 URL 白名单：每个应用可配置 1～5 个 HTTPS 地址前缀。
• recipientId：余额分账申请使用的、已完成系统审核并生效的分账接收方标识。订单分账申请不使用该字段，改用实际分账接收商户号。

完整密钥只在创建或重置成功后展示一次。调用方必须立即保存到服务端密钥管理系统，不得写入浏览器前端、小程序、APP、日志或代码仓库。

应用状态说明：

• 启用：允许使用该 appId 发起新的开放接口请求。
• 停用：拒绝新的开放接口请求；停用前已登记的业务回调仍可能继续投递。
• 默认应用：仅用于商户系统中的默认选择，不改变签名和接口权限。

密钥轮换说明：

• 重置后旧密钥立即失效，调用方应先安排维护窗口并确保服务端配置可以同步切换。
• 系统不会提供“查看原密钥”能力；遗失密钥只能重置。

1.1 身份与商户号

• appId + apiSecret 用于证明请求来自本系统已启用的合法应用。
• apiSecret 不作为 JSON 字段传输；调用方使用它计算 X-Signature。
• 支付、退款和余额分账使用 merchantNo，系统校验该资金商户号已绑定当前应用所属商户账号。
• 订单分账的 receiveMerchantNo 表示实际分账接收商户号，不是原支付订单的收款商户号，也不要求绑定当前开放应用。系统根据 outTradeNo 自动取得原订单收款商户号并校验该原订单及其资金商户属于当前应用。
• 支付、退款、分账请求中的 notifyUrl 是业务方最终接收通知的地址，必须命中应用回调白名单。
• 支付机构路由、报文转换、查单和异常归一化均由系统内部完成，调用方无需也无法获知底层渠道信息。

2. 统一响应

{
  "code": "00000",
  "msg": "成功",
  "data": {}
}

3. 请求鉴权

开放 API 不提供登录接口，也不接收商户后台 JWT、Authorization: Bearer 或登录 Cookie。调用方直接使用在“应用管理”中取得的 appId 和 apiSecret 对每个请求独立签名；验签通过即代表该应用身份合法。

每个请求必须携带：

除上述请求头外无需传登录令牌。缺少签名、签名错误、时间戳过期、nonce 重复、应用停用或应用不存在时，系统返回 HTTP 401；开放接口未启用或防重放服务不可用时返回 HTTP 503。

待签名串由六行组成，末尾不追加换行：

HTTP_METHOD
REQUEST_PATH
RAW_QUERY_STRING
X_TIMESTAMP
X_NONCE
SHA256_HEX(RAW_BODY_BYTES)

计算方式：

X-Signature = hex_lower(
  HMAC_SHA256(apiSecret, canonicalString)
)

注意：

• REQUEST_PATH 只包含路径，例如 /openapi/v1/payments。
• RAW_QUERY_STRING 必须与实际发送内容完全一致；无查询参数时为空行。
• 请求体哈希基于实际发送的 UTF-8 字节。签名后不能重新格式化 JSON。
• 时间戳允许偏差以系统配置为准，默认不超过 5 分钟。
• nonce 重复会被判定为重放请求。

Python 签名工具类（以下所有接口示例均基于此工具类）：

import hashlib
import hmac
import json
import secrets
import time
import urllib.request


class OpenApiClient:
    def __init__(self, base_url: str, app_id: str, api_secret: str):
        self.base_url = base_url
        self.app_id = app_id
        self.api_secret = api_secret

    def post(self, path: str, payload: dict) -> str:
        body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
        return self._do_request("POST", path, "", body)

    def get(self, path: str, raw_query: str = "") -> str:
        return self._do_request("GET", path, raw_query, b"")

    def _do_request(self, method: str, path: str, raw_query: str, body: bytes) -> str:
        timestamp = str(int(time.time()))
        nonce = secrets.token_hex(16)
        body_hash = hashlib.sha256(body).hexdigest()
        canonical = "\n".join([method, path, raw_query, timestamp, nonce, body_hash])
        signature = hmac.new(
            self.api_secret.encode("utf-8"),
            canonical.encode("utf-8"),
            hashlib.sha256,
        ).hexdigest()

        url = self.base_url + path + (("?" + raw_query) if raw_query else "")
        req = urllib.request.Request(url, data=body if body else None, method=method)
        req.add_header("X-App-Id", self.app_id)
        req.add_header("X-Timestamp", timestamp)
        req.add_header("X-Nonce", nonce)
        req.add_header("X-Signature", signature)
        if method == "POST":
            req.add_header("Content-Type", "application/json; charset=UTF-8")

        with urllib.request.urlopen(req) as resp:
            return resp.read().decode("utf-8")

Java 签名工具类（以下所有接口示例均基于此工具类）：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.math.BigInteger;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Instant;

public class OpenApiClient {

    private static final SecureRandom RANDOM = new SecureRandom();
    private final HttpClient http = HttpClient.newHttpClient();
    private final String baseUrl;
    private final String appId;
    private final String apiSecret;

    public OpenApiClient(String baseUrl, String appId, String apiSecret) {
        this.baseUrl = baseUrl;
        this.appId = appId;
        this.apiSecret = apiSecret;
    }

    /** POST 请求 */
    public String post(String path, String jsonBody) throws Exception {
        return doRequest("POST", path, "", jsonBody);
    }

    /** GET 请求（无请求体） */
    public String get(String path, String rawQuery) throws Exception {
        return doRequest("GET", path, rawQuery, "");
    }

    private String doRequest(String method, String path, String rawQuery, String jsonBody) throws Exception {
        String timestamp = String.valueOf(Instant.now().getEpochSecond());
        String nonce = randomNonce();
        byte[] bodyBytes = jsonBody.getBytes(StandardCharsets.UTF_8);
        String bodyHash = sha256Hex(bodyBytes);
        String canonical = String.join("\n", method, path, rawQuery, timestamp, nonce, bodyHash);
        String signature = hmacSha256Hex(apiSecret, canonical);

        URI uri = rawQuery.isEmpty()
                ? URI.create(baseUrl + path)
                : URI.create(baseUrl + path + "?" + rawQuery);

        HttpRequest.Builder builder = HttpRequest.newBuilder(uri)
                .header("X-App-Id", appId)
                .header("X-Timestamp", timestamp)
                .header("X-Nonce", nonce)
                .header("X-Signature", signature);

        if ("POST".equals(method)) {
            builder.header("Content-Type", "application/json; charset=UTF-8")
                    .POST(HttpRequest.BodyPublishers.ofByteArray(bodyBytes));
        } else {
            builder.GET();
        }

        HttpResponse<String> resp = http.send(builder.build(), HttpResponse.BodyHandlers.ofString());
        return resp.body();
    }

    private static String sha256Hex(byte[] data) throws Exception {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] hash = md.digest(data);
        return new BigInteger(1, hash).toString(16);
    }

    private static String hmacSha256Hex(String secret, String data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        return new BigInteger(1, hash).toString(16);
    }

    private static String randomNonce() {
        byte[] buf = new byte[16];
        RANDOM.nextBytes(buf);
        return new BigInteger(1, buf).toString(16);
    }
}

4. 幂等与状态处理

• 支付使用 outTradeNo 幂等。
• 退款使用 refundRequestNo 幂等。
• 分账使用 businessNo 幂等。
• 同一业务重试必须保持业务单号、金额、回调地址及关键业务参数不变。
• 写请求超时或返回不确定结果时，先使用原业务单号查询，禁止立即生成新单号。
• 回调和主动查询均可能重复或乱序，调用方必须按业务单号和状态机幂等处理。

5. 支付

5.1 创建支付

POST /payments

请求字段：

paymentMode 支持：

Java 示例：

OpenApiClient client = new OpenApiClient("https://{api-host}/openapi/v1", appId, apiSecret);

String body = """
    {
      "merchantNo": "10080000001",
      "outTradeNo": "ORDER202607300001",
      "amount": 1.00,
      "paymentMethod": "WECHAT",
      "paymentMode": "USER_SCAN",
      "goodsName": "测试商品",
      "userIp": "203.0.113.10",
      "notifyUrl": "https://merchant.example.com/callbacks/payment",
      "settlementMode": "IMMEDIATE"
    }
    """;

String result = client.post("/payments", body);
System.out.println(result);

Python 示例：

client = OpenApiClient("https://{api-host}/openapi/v1", app_id, api_secret)

result = client.post("/payments", {
    "merchantNo": "10080000001",
    "outTradeNo": "ORDER202607300001",
    "amount": 1.00,
    "paymentMethod": "WECHAT",
    "paymentMode": "USER_SCAN",
    "goodsName": "测试商品",
    "userIp": "203.0.113.10",
    "notifyUrl": "https://merchant.example.com/callbacks/payment",
    "settlementMode": "IMMEDIATE"
})
print(result)

响应 data 字段：

paymentData 是支付唤起凭证，可能是 URL 或 JSON 字符串。调用方应按已开通的 paymentMode 处理，不应解析或依赖未在系统接入说明中约定的扩展字段。

支付状态：

5.2 查询支付

GET /payments/{outTradeNo}?merchantNo={merchantNo}&refresh=true

• 建议在未收到回调时按 5 秒、15 秒、30 秒、60 秒递增查询，达到业务超时后停止。

Java 示例：

String result = client.get(
    "/payments/ORDER202607300001",
    "merchantNo=10080000001&refresh=true");
System.out.println(result);

Python 示例：

result = client.get(
    "/payments/ORDER202607300001",
    "merchantNo=10080000001&refresh=true")
print(result)

响应 data 字段同 5.1。

6. 退款

6.1 申请退款

POST /refunds

请求字段：

Java 示例：

String body = """
    {
      "merchantNo": "10080000001",
      "refundRequestNo": "REFUND_20260730_0001",
      "outTradeNo": "ORDER202607300001",
      "amount": 1.00,
      "reason": "用户取消订单",
      "notifyUrl": "https://merchant.example.com/callbacks/refund"
    }
    """;

String result = client.post("/refunds", body);
System.out.println(result);

Python 示例：

result = client.post("/refunds", {
    "merchantNo": "10080000001",
    "refundRequestNo": "REFUND_20260730_0001",
    "outTradeNo": "ORDER202607300001",
    "amount": 1.00,
    "reason": "用户取消订单",
    "notifyUrl": "https://merchant.example.com/callbacks/refund"
})
print(result)

响应 data 字段：

退款状态：

nextAction 可能为：

6.2 查询退款

GET /refunds/{refundRequestNo}?merchantNo={merchantNo}&refresh=true

• 调用方不能仅依赖同步申请响应，必须实现回调和查询补偿。

Java 示例：

String result = client.get(
    "/refunds/REFUND_20260730_0001",
    "merchantNo=10080000001&refresh=true");
System.out.println(result);

Python 示例：

result = client.get(
    "/refunds/REFUND_20260730_0001",
    "merchantNo=10080000001&refresh=true")
print(result)

响应 data 字段同 6.1。

7. 订单分账

发起订单分账前必须满足：

• 原支付订单属于当前调用方、系统订单状态为 SUCCESS，且未发生全额退款。支付机构状态仍显示支付成功，但系统订单状态已变为 REFUNDED 时不能分账。
• 创建支付时 settlementMode=DELAYED。
• 当 paymentMode=USER_SCAN 时，系统收银台会在实际发起支付时继承该结算模式；创建订单后不能再切换。
• receiveMerchantNo 对应的实际接收商户已具备有效的订单分账接收能力。
• 分账金额和比例不超过订单当前可分账余额。

字段封装边界：

• 调用方只传系统业务字段。支付机构发起方信息、支付机构订单信息、内部请求标识、接收方类型、路由及扩展信息均由系统根据原支付订单和本次申请在内部转换、补齐。
• businessNo 是调用方幂等键，中台据此生成并保存内部请求标识；调用方不得改用支付机构请求号重试或查询。
• outTradeNo 必须是本系统创建支付时使用的调用方订单号。中台校验订单归属后，从订单记录取得底层支付单信息。
• receiveMerchantNo 是资金实际转入的商户号；原支付订单的收款商户号由 outTradeNo 自动解析，两者不得混用。
• 订单分账请求不接收 merchantNo 或 recipientId，当前一次申请只支持一个实际接收商户和一条分账明细。
• notifyUrl 只用于系统向调用方发送统一结果通知，不作为底层渠道字段透传。

7.1 发起订单分账

POST /profit-sharing/orders

请求字段：

Java 示例：

String body = """
    {
      "receiveMerchantNo": "10080000002",
      "businessNo": "ALLOC_ORDER_20260730_0001",
      "outTradeNo": "ORDER202607300001",
      "notifyUrl": "https://merchant.example.com/callbacks/profit-sharing",
      "allocationMode": "AMOUNT",
      "releaseRemainingAmount": false,
      "details": [
        {
          "amount": 0.80,
          "description": "服务费分账"
        }
      ]
    }
    """;

String result = client.post("/profit-sharing/orders", body);
System.out.println(result);

Python 示例：

result = client.post("/profit-sharing/orders", {
    "receiveMerchantNo": "10080000002",
    "businessNo": "ALLOC_ORDER_20260730_0001",
    "outTradeNo": "ORDER202607300001",
    "notifyUrl": "https://merchant.example.com/callbacks/profit-sharing",
    "allocationMode": "AMOUNT",
    "releaseRemainingAmount": False,
    "details": [
        {
            "amount": 0.80,
            "description": "服务费分账"
        }
    ]
})
print(result)

按比例时：

• allocationMode=PERCENTAGE；按金额时可省略 allocationMode，默认 AMOUNT。
• 必须填写 allocationBaseAmount，单位：元。
• 唯一明细填写 percentage=100，最多两位小数；allocationBaseAmount 是本次按比例计算的基准金额。
• 明细中的 amount 不填写。
• releaseRemainingAmount 只能为 false 或不传。

按金额时：

• 唯一明细必须填写 amount，最多两位小数，不限制为 100 元以内；明细中的 percentage 不填写。
• 不得填写 allocationBaseAmount。
• releaseRemainingAmount=true 表示本次处理后不再继续对该订单剩余金额分账，请仅在业务确认分账结束时使用。
• 明细不再填写 recipientId；其实际接收方就是请求顶层的 receiveMerchantNo。

7.2 查询订单分账

GET /profit-sharing/orders/{businessNo}?receiveMerchantNo={receiveMerchantNo}

查询接口只接收上述两个业务字段。中台先按当前应用和 businessNo 定位原申请，再校验 receiveMerchantNo 与原申请的实际接收商户一致，并自动取得查询所需的原订单信息；不接收原订单收款商户号、支付机构订单号或内部请求标识。若申请结果不确定，必须使用原 businessNo 和原 receiveMerchantNo 查询，不能换号。

Java 示例：

String result = client.get(
    "/profit-sharing/orders/ALLOC_ORDER_20260730_0001",
    "receiveMerchantNo=10080000002");
System.out.println(result);

Python 示例：

result = client.get(
    "/profit-sharing/orders/ALLOC_ORDER_20260730_0001",
    "receiveMerchantNo=10080000002")
print(result)

响应 data 字段见 8.3。

7.3 申请订单分账资金归还

POST /profit-sharing/order-returns

该接口用于将一笔已成功的订单分账金额归还至原支付订单。一次订单分账申请当前只支持一条分账明细，因此归还时系统根据原支付订单自动定位已成功的分账明细；调用方不传接收商户号、系统请求号或支付机构的订单和分账明细标识。

前置条件：原支付订单属于当前开放应用、原订单分账已成功，且本次归还金额不超过该原分账明细的可归还金额。

请求字段：

Java 示例：

String body = """
    {
      "outTradeNo": "ORDER202607300001",
      "businessNo": "RETURN_ORDER_20260730_0001",
      "amount": 0.80,
      "reason": "售后归还"
    }
    """;

String result = client.post("/profit-sharing/order-returns", body);
System.out.println(result);

Python 示例：

result = client.post("/profit-sharing/order-returns", {
    "outTradeNo": "ORDER202607300001",
    "businessNo": "RETURN_ORDER_20260730_0001",
    "amount": 0.80,
    "reason": "售后归还"
})
print(result)

响应 data 字段：

不会返回也不会接收原支付收款商户号、实际接收商户号、系统内部请求号、底层支付订单号、底层分账请求号或分账明细号。

7.4 查询订单分账资金归还结果

GET /profit-sharing/order-returns/{businessNo}?outTradeNo={outTradeNo}

系统先校验订单归属，再用内部保存的关联信息查询最新状态；查询响应字段与 7.3 相同。状态不确定时必须使用原 businessNo 查询，不能更换新的业务单号。

Java 示例：

String result = client.get(
    "/profit-sharing/order-returns/RETURN_ORDER_20260730_0001",
    "outTradeNo=ORDER202607300001");
System.out.println(result);

Python 示例：

result = client.get(
    "/profit-sharing/order-returns/RETURN_ORDER_20260730_0001",
    "outTradeNo=ORDER202607300001")
print(result)

8. 余额分账

余额分账不依赖原支付订单，只允许向系统已审核生效的 recipientId 分账。

8.1 发起余额分账

POST /profit-sharing/balances

请求字段：

Java 示例：

String body = """
    {
      "merchantNo": "10080000001",
      "businessNo": "ALLOC_BALANCE_20260730_0001",
      "notifyUrl": "https://merchant.example.com/callbacks/profit-sharing",
      "details": [
        {
          "recipientId": "RECIPIENT_0001",
          "amount": 10.00,
          "description": "业务分润",
          "feeMode": "DEDUCT_FROM_AMOUNT",
          "purpose": "服务费"
        }
      ]
    }
    """;

String result = client.post("/profit-sharing/balances", body);
System.out.println(result);

Python 示例：

result = client.post("/profit-sharing/balances", {
    "merchantNo": "10080000001",
    "businessNo": "ALLOC_BALANCE_20260730_0001",
    "notifyUrl": "https://merchant.example.com/callbacks/profit-sharing",
    "details": [
        {
            "recipientId": "RECIPIENT_0001",
            "amount": 10.00,
            "description": "业务分润",
            "feeMode": "DEDUCT_FROM_AMOUNT",
            "purpose": "服务费"
        }
    ]
})
print(result)

8.2 查询余额分账

GET /profit-sharing/balances/{businessNo}?merchantNo={merchantNo}

Java 示例：

String result = client.get(
    "/profit-sharing/balances/ALLOC_BALANCE_20260730_0001",
    "merchantNo=10080000001");
System.out.println(result);

Python 示例：

result = client.get(
    "/profit-sharing/balances/ALLOC_BALANCE_20260730_0001",
    "merchantNo=10080000001")
print(result)

响应 data 字段见 8.3。

8.3 分账响应

订单分账和余额分账使用统一响应。

响应 data 字段：

分账状态：

余额分账在成功后仍可能因后续退回而更新为失败。调用方不得用“成功后永不变化”的状态机处理余额分账，应以最新事件为准。

9. 业务回调

事件类型：

回调请求头：

回调体字段：

回调体示例：

{
  "eventId": "7edb6c9a-1f7d-4aa7-a147-16c8c9ef73d4",
  "eventType": "refund.status.changed",
  "occurredAt": "2026-07-30T09:40:00Z",
  "appId": "app_0123456789abcdef01234567",
  "merchantNo": "10080000001",
  "businessNo": "REFUND_20260730_0001",
  "status": "SUCCESS",
  "data": {}
}

接收要求：

1. 校验 appId 和 merchantNo 与本应用一致。
2. 使用 eventId 做幂等去重。
3. 根据 eventType + businessNo 更新业务状态，并允许合法的后续状态修正。
4. 处理成功后返回 HTTP 2xx，响应体必须是纯文本 SUCCESS。
5. 非 2xx 或响应体不是 SUCCESS 会触发重试；调用方不得依赖固定重试次数或间隔。