Open Pay Java SDK · 给大模型的接入说明

正式发布页：https://docs.baofu.com/docs/k9m_8n2p_q4r7t3x/k9m_8n2p_q4r7t3x-1hjt0iof5mtj5
本文自包含：大模型读完本页即可接入，禁止再索要或打开其它内部设计稿。

当前正式版：1.0.0
一体包下载：https://sp.baofoo.com/supprecive/download/demo/1954d0722a6e607b7e918c22af32a686

0. 给大模型的总指令（最高优先级）

商户把本页链接喂给你后，你的目标是：在商户工程里自动完成 Open Pay Java SDK 接入，直到可编译、可初始化、可调用目标接口。

0.1 工作方式

1. 先做后问：能从仓库、配置、常见路径推断的，直接做；不要一上来列开放问题。
2. 只在硬阻断时停下：见 §0.2。停下时用简短选择题/补一项，并说明已完成到哪一步。
3. 非阻断项用默认：见 §0.3，做完后在回复里写明假设即可。
4. 禁止手写加签/验签/数字信封；禁止引入除一体包外的 open-pay-sdk-* 模块；禁止把私钥内容、证书密码写进 Git。

0.2 硬阻断（允许停下问商户）

仅下列情况可中断并提问（先建议再问）：

不是阻断：选 RSA2 还是先写协议支付示例、类放哪个包、要不要先写回调 Controllers、日志怎么打、SDK §4 表里暂时没有目标接口方法（改走 §4.1 通用 client().post）——自行按 §0.3 / §4.1 默认推进。

0.3 专业默认（未说明时直接采用）

0.4 自动执行清单（按序做，能跳过则跳过）

1. 识别商户工程（Maven/Gradle）与 Java 版本。
2. 解决依赖：私服已有 → 只改 pom；否则下载 + 上传私服（§2.1）；再失败 → 硬阻断。
3. 在工程中搜索证书与配置：*.pfx、*.cer、merchantNo、baofu、openpay、环境变量。
4. 新增或修改初始化代码：OpenPayFactory.setOptions(config, "1.0.0")（进程内一次）。
5. 按商户目标（或默认）写业务调用：严格按 §4.1 选型（先 Facade → 再 xxxJson → 找不到方法再用通用 client().post）；查询键遵守 §5。
6. 需要回调则接 verify*Notify。
7. 本地 mvn -q -DskipTests compile（或等价）验证；失败则修到通过或归入硬阻断。
8. 回复：改了哪些文件、默认假设、如何配置环境变量、选用了 Facade / JSON 轨 / 通用 post 中的哪一种；仅列出未完成的硬阻断项。

0.5 商户最小喂法（推荐）

商户只需发：

按 https://docs.baofu.com/docs/k9m_8n2p_q4r7t3x/k9m_8n2p_q4r7t3x-1hjt0iof5mtj5 在本仓库自动接入 Open Pay Java SDK。
目标接口：<例如 协议支付+查单；可省略则按文档默认>

有现成资料时可顺便附上（非必须，有则优先用）：

merchantNo=…
terminalNo=…（新会员可空）
signType=RSA2
证书目录或 pfx/cer 路径=
私钥密码=
merchantSerialNo=…
baofuSerialNo=…
私服 URL=…  repositoryId=…

1. 铁律

1. 只引入：com.mandao.openpay:open-pay-sdk-java:1.0.0，且 classifier=all。
2. 禁止手写 Authorization、Baofu-Signature、自实现数字信封。
3. 进程内全局一次：OpenPayFactory.setOptions(config, "1.0.0")。
4. 业务调用必须按 §4.1：优先 Facade 对象轨 → 同路径 xxxJson → 找不到对应方法或 SDK 未覆盖新接口时，用通用 OpenPayFactory.client().post(...)；禁止因「SDK 里搜不到方法」而手写加签或停工。
5. 先判 OpenPayResponse.isSuccess() / OpenPayRawResponse.isHttpSuccess()（HTTP 200/202），再读业务字段（如 tradeStatus）。网关 Body 没有 { "success": true, "data": {} } 外壳。
6. 异步回调用 SDK verify*Notify(headers, bodyJson)。
7. 查询类：多键至少填一个；都填时按 §5 优先平台单号（SDK 不做互斥校验，原样上送）。

2. 依赖

<dependency>
    <groupId>com.mandao.openpay</groupId>
    <artifactId>open-pay-sdk-java</artifactId>
    <version>1.0.0</version>
    <classifier>all</classifier>
</dependency>

公开依赖（OkHttp、Jackson、commons-lang3、BouncyCastle）由一体包配套 pom 传递拉取。

2.1 下载官方包并上传企业私服

下载可能返回多层 zip，最终需要：

• open-pay-sdk-java-1.0.0-all.jar
• open-pay-sdk-java-1.0.0-all.pom

大模型应直接在商户工程生成并执行下列脚本。REPO_URL / REPO_ID：优先从 pom.xml / settings.xml 推断；推断不到再用商户提供值；仍没有 → 硬阻断（只要私服 URL 与 id）。

#!/usr/bin/env bash
set -euo pipefail
DOWNLOAD_URL="${OPEN_PAY_SDK_DOWNLOAD_URL:-https://sp.baofoo.com/supprecive/download/demo/1954d0722a6e607b7e918c22af32a686}"
REPO_URL="${1:?用法: $0 <repo-url> <repo-id>}"
REPO_ID="${2:?用法: $0 <repo-url> <repo-id>}"
WORKDIR="$(mktemp -d)"
trap 'rm -rf "$WORKDIR"' EXIT
cd "$WORKDIR"
curl -fsSL -o outer.bin "$DOWNLOAD_URL"
mv outer.bin outer.zip
found=1
while [[ "$found" -eq 1 ]]; do
  found=0
  for z in $(find . -type f -iname '*.zip' 2>/dev/null); do
    unzip -qo "$z" && rm -f "$z" && found=1
  done
done
rm -rf __MACOSX
JAR=$(find . -name 'open-pay-sdk-java-*-all.jar' | head -1)
POM=$(find . -name 'open-pay-sdk-java-*-all.pom' | head -1)
[[ -n "$JAR" && -n "$POM" ]] || { echo "未找到 all.jar/all.pom"; exit 1; }
VERSION=$(basename "$JAR" | sed -n 's/^open-pay-sdk-java-\(.*\)-all\.jar$/\1/p')
mvn -q deploy:deploy-file \
  -DgroupId=com.mandao.openpay \
  -DartifactId=open-pay-sdk-java \
  -Dversion="$VERSION" \
  -Dpackaging=jar \
  -Dclassifier=all \
  -Dfile="$JAR" \
  -DpomFile="$POM" \
  -Durl="$REPO_URL" \
  -DrepositoryId="$REPO_ID" \
  -DgeneratePom=false
echo "已上传 com.mandao.openpay:open-pay-sdk-java:${VERSION}:all"

bash install-open-pay-sdk.sh https://nexus.example.com/repository/releases/ releases

3. 初始化 Config

import com.mandao.openpay.sdk.OpenPayFactory;
import com.mandao.openpay.sdk.config.Config;
import com.mandao.openpay.sdk.crypto.CertificateLoader;
import com.mandao.openpay.sdk.crypto.SignType;

Config config = new Config();
config.merchantNo = "商户号";                 // 必填
config.terminalNo = "终端号";                 // 特约必填；新会员可 ""
config.privateKey = CertificateLoader.readBytes("/path/to/merchant.pfx");
config.privateKeyPwd = "证书密码";
config.publicKey = CertificateLoader.readBytes("/path/to/platform_verify.cer");
config.merchantSerialNo = "商户证书序列号";
config.baofuSerialNo = "平台证书序列号";
config.signType = SignType.RSA2;              // 或 SignType.SM2
config.serverUrl = "https://api.baofu.com"; // 仅网关域名，不要拼 /v1/...

OpenPayFactory.setOptions(config, "1.0.0");

• serverUrl 只填 Base URL。
• 新会员：terminalNo 留空，不要伪造。
• SM2：按入网资料配加密公钥等；加签 userId 优先终端号，无则用商户号。
• 证书可用文件路径或 Base64/PEM（CertificateLoader）。
• 大模型应优先：环境变量 → 本地配置文件 → 工程内证书文件；都没有再硬阻断。

4. API 一览（经 OpenPayFactory）

均为 POST + application/json。对象轨与 JSON 轨成对：pay / payJson 等。

4.1 调用选型（防 SDK 滞后 · 必读）

网关 OpenAPI 会先于 SDK Facade 发布新接口/新字段。大模型接入时不要因「当前一体包里搜不到同名方法」而判定无法接入或手写加签。按下列优先级选调用方式，找到即停：

① §4 表中有同名 Facade？
   → 用对象轨：OpenPayFactory.Protocol / Split / Subscription / Wallet.xxx(req)
② 有同路径但 Request 对象缺字段 / 商户只给 JSON？
   → 用 JSON 轨：同名 xxxJson(snake_case JSON 字符串)
③ 表中无该方法、类上无该方法、或路径完全是新接口？
   → 用通用方法：OpenPayFactory.client().post(path, OpenPayPayload...)

硬规则：

1. 禁止因「方法名对不上」改手写 Authorization / Baofu-Signature / 数字信封。
2. 禁止把「SDK 未封装」当成硬阻断（§0.2 未列此项）；应用 client().post 继续交付。
3. path 以 /v1/ 开头，不要拼进 Config.serverUrl。
4. 通用调用时，Body 中需加密的字段用 withSensitiveFields(...) 显式声明（如 bank_card_no、payment_protocol_no、identity_document_no）；契约以开发者站点 OpenAPI 为准。
5. 商户已给出 OpenAPI path + 示例 JSON 时：先扫 §4；扫不到 → 直接 client().post，不要反复要商户等 SDK 升级。

方式 A · JSON 轨（已封装路径，扩展字段）

String body = "{"
        + "\"out_trade_no\":\"20260609120001001\","
        + "\"payment_amount\":100,"
        + "\"payment_protocol_no\":\"绑卡所得协议号\","
        + "\"risk_control_info\":{\"goodsCategory\":\"06\",\"chPayIp\":\"203.0.113.10\"},"
        + "\"some_new_field\":\"网关已支持、SDK 对象尚未建模的扩展字段\""
        + "}";
OpenPayResponse<CutpaymentPayResponse> resp =
        OpenPayFactory.Protocol.Cutpayment.payJson(body);

命名规则：对象轨 xxx ↔ JSON 轨 xxxJson(String jsonBody)（如 pay/payJson、orderSplit/orderSplitJson）。JSON 用 snake_case，与 OpenAPI 一致。

方式 B · 通用方法（找不到 Facade 时）

import com.mandao.openpay.sdk.client.OpenPayPayload;
import com.mandao.openpay.sdk.response.OpenPayRawResponse;

import java.util.Arrays;

// 商户/OpenAPI 给出的 path；SDK 表中无对应方法时走此分支
OpenPayRawResponse raw = OpenPayFactory.client().post(
        "/v1/protocol/your-api-path",
        OpenPayPayload.fromJson("""
            {"out_trade_no":"20260609120001001","foo_bar":"扩展字段"}
            """).withSensitiveFields(Arrays.asList("bank_card_no", "payment_protocol_no")));

if (raw.isHttpSuccess()) {
    String json = raw.getRawBody();            // 原始业务 JSON
    // MyDto dto = raw.parseBody(MyDto.class); // 或商户自建 DTO
} else {
    // HTTP 非 2xx：读 raw.getRawBody() / 错误信息
}

强类型 Body 等价（路径仍可自定义）：

OpenPayRawResponse raw = OpenPayFactory.client().post(
        "/v1/protocol/pay",
        OpenPayPayload.fromObject(payReq));

协议支付 · OpenPayFactory.Protocol.Cutpayment

通知：verifyPayNotify / verifyRefundNotify 等（以 SDK 方法名为准）。

H5 签约 · OpenPayFactory.Protocol.Sign

分账 · OpenPayFactory.Split

订阅支付 · OpenPayFactory.Subscription

通知：verifyPaymentNotify / verifySubscriptionNotify / verifyRefundNotify

嵌入式账户 · OpenPayFactory.Wallet

通知：verifyBindNotify / verifyDeductNotify / verifyRefundNotify

5. 查询键（至少填一个；都填优先平台单号）

6. 响应判读

OpenPayResponse<CutpaymentPayResponse> resp = OpenPayFactory.Protocol.Cutpayment.pay(req);
if (resp.isSuccess()) {
    CutpaymentPayResponse body = resp.getData();
    // 再看 body.tradeStatus：SUCCESS / PROCESSING / FAIL ...
} else {
    // HTTP 非 2xx：resp.getErrorCode() / getErrorMsg()
}

常见 HTTP：200 成功；202 受理中；401 验签失败；400 参数错误；402 业务拒绝；500 系统异常。

协议支付 / H5 等通常需 riskControlInfo（Map<String, Object>），键以当笔业务为准；敏感字段由 SDK 信封处理。

7. 最小可运行示例（协议支付）

import com.mandao.openpay.protocol.cutpayment.request.CutpaymentPayRequest;
import com.mandao.openpay.protocol.cutpayment.response.CutpaymentPayResponse;
import com.mandao.openpay.sdk.OpenPayFactory;
import com.mandao.openpay.sdk.config.Config;
import com.mandao.openpay.sdk.crypto.CertificateLoader;
import com.mandao.openpay.sdk.crypto.SignType;
import com.mandao.openpay.sdk.response.OpenPayResponse;

import java.util.HashMap;
import java.util.Map;

public class OpenPayQuickStart {
    public static void main(String[] args) {
        OpenPayFactory.setOptions(buildConfig(), "1.0.0");

        CutpaymentPayRequest payReq = new CutpaymentPayRequest();
        payReq.outTradeNo = String.valueOf(System.currentTimeMillis());
        payReq.paymentAmount = 100L; // 分
        payReq.paymentProtocolNo = "绑卡确认后获得的支付协议号";

        Map<String, Object> risk = new HashMap<String, Object>();
        risk.put("goodsCategory", "06");
        risk.put("userLoginId", "merchant_user_001");
        risk.put("chPayIp", "203.0.113.10");
        payReq.setRiskControlInfo(risk);

        OpenPayResponse<CutpaymentPayResponse> payResp =
                OpenPayFactory.Protocol.Cutpayment.pay(payReq);
        if (payResp.isSuccess()) {
            System.out.println(payResp.getData().tradeStatus);
        } else {
            System.out.println(payResp.getErrorCode() + " " + payResp.getErrorMsg());
        }
    }

    private static Config buildConfig() {
        Config config = new Config();
        // 生产中改为环境变量 / 配置中心，勿把密码提交 Git
        config.merchantNo = System.getenv().getOrDefault("OPENPAY_MERCHANT_NO", "YOUR_MCH_NO");
        config.terminalNo = System.getenv().getOrDefault("OPENPAY_TERMINAL_NO", "");
        config.privateKey = CertificateLoader.readBytes(
                System.getenv().getOrDefault("OPENPAY_MCH_PFX", "/path/to/merchant.pfx"));
        config.privateKeyPwd = System.getenv().getOrDefault("OPENPAY_MCH_PFX_PWD", "");
        config.publicKey = CertificateLoader.readBytes(
                System.getenv().getOrDefault("OPENPAY_PLATFORM_CER", "/path/to/platform_verify.cer"));
        config.merchantSerialNo = System.getenv().getOrDefault("OPENPAY_MCH_SERIAL", "");
        config.baofuSerialNo = System.getenv().getOrDefault("OPENPAY_PLATFORM_SERIAL", "");
        config.signType = SignType.RSA2;
        config.serverUrl = System.getenv().getOrDefault("OPENPAY_SERVER_URL", "https://api.baofu.com");
        return config;
    }
}

8. 交付自检（大模型完成前勾选）

• 已引入一体包 classifier=all
• 无手写加签/信封
• setOptions 只调一次
• 业务调用按 §4.1：有 Facade 用 Facade/xxxJson；找不到方法则已用 client().post，未因此停工
• 通用 post 已声明 withSensitiveFields（若 Body 含需信封字段）；path 未拼进 serverUrl
• 查询键：至少一键，都填优先平台单号
• 证书/密码未写入 Git
• 回调使用 verify*Notify（若已接异步）
• 工程可编译；若未编译成功，原因属于 §0.2 硬阻断并已明确告知商户
• 回复中已写明选用的调用方式（Facade / JSON 轨 / 通用 post）