朝合支付OPEN PLATFORM 开放平台
查找接口 申请接入
朝合开放平台 · 商户进件与聚合支付，一次连接

商户进件与支付开放接口体系

一次对接，完成个体工商户、企业、小微三类主体的商户入网；开通收款能力后，用同一套签名完成支付下单、结果通知、订单及账户余额查询。

申请接入与获取密钥 查看接口文档 联调探针

平台提供商户进件、聚合支付、支付与资金结果通知、订单与资金查询、余额分账、结算方向配置及自助结算。退款、资金账户余额提现及对账文件暂未开放，查看能力边界。

POST /api/open.merchant/prePay
{
  "app_id": "ak_********",
  "timestamp": "1786777149",
  "nonce": "dev_e57c46f3ec3e",
  "channel": "yibao",
  "merchantNo": "你的商户号",
  "orderAmount": "0.01",
  "payWay": "USER_SCAN",
  "sign": "按签名规则计算"
}
报文示例 · 不会发送支付请求
Entity Types
3 类 商户主体：个体 / 企业 / 小微
Signature
2 种 签名方式：HMAC-SHA256 / RSA2
Replay Window
±300s 时间戳容差，超出即拒绝
REST Endpoints
29 个 签名接口条目，按需授权

Capability

进件与收款，一条链路做完

从准备商户资料、提交入网申请，到开通支付并确认交易结果，按照下方步骤完成接入。

02

基础数据由服务端下发

地区编码、行业类目（MCC）、银行与支行查询接口直接可用，无需自行维护与同步字典。

地区 · MCC · 银行 · 支行 ↗

03

全流程状态可查

进件进度、商户状态、资料变更进度均可主动查询，便于在你方系统内展示并驱动后续流程。

registerQry / merchantStatusQry ↗

04

结果回调到你的地址

审核完成后异步推送至进件时指定的回调地址；同时保留查询接口，作为回调丢失时的兜底。

callbackurl + 主动查询兜底 ↗

05

进件成功即可收款

商户状态为「成功」后，用同一个 merchantNo 调下单接口即可收款，支持扫码、公众号、生活号、小程序、微信 SDK 和支付宝 H5 支付。

prePay · 聚合支付下单 ↗

06

选择资金处理方式

下单时选择自动处理商户余款，或保留余款待后续处理。使用前请确认应用已开通的能力范围。

prePay · 下单参数说明 ↗

Integration

四步接入

无需 SDK，标准 HTTP + 签名即可完成对接。已有签名逻辑的项目，通常只增加一个签名函数与数个请求。

  1. 申请接入

    提交接入申请，平台下发 app_id 与密钥：HMAC-SHA256 轨使用共享密钥；RSA2 轨需登记你方公钥。

  2. 完成签名

    剔除 sign 与空值，按键名 ASCII 升序拼成 k=v&k=v，再用密钥加签。请求须携带 timestamp 与 nonce。

  3. 提交进件

    提交主体资料，etpsAttr 区分：1 个体、2 企业、3 小微。审核结果推送至回调地址，也可主动查询进度。

  4. 发起收款

    商户开通收款能力后，使用 prePay 获取二维码或支付调起参数，并通过通知或订单查询确认交易结果。

Authentication

公共参数与签名

所有开放接口（含 upload）均需请求签名。以下公共参数与业务参数平铺提交；建议复用公共客户端。

01 · 公共请求参数

参数类型必填 / 位置说明
app_idstring是应用标识；应用须启用并满足本接口 scope 与来源 IP 白名单。
sign_typestring否本次签名算法；须与应用开通的签名方式一致。 取值：HMAC-SHA256 / RSA2。 默认："HMAC-SHA256"。
timestampstring是每次请求生成当前秒级时间戳，允许偏差 ±300 秒；兼容毫秒时间戳。
noncestring是每次请求生成新的随机串，同一应用 600 秒内不可重复。
signstring是对全部公共参数、业务参数和 URL 查询参数签名；剔除 sign 自身及空字符串/null。数组转未转义中文和斜杠的 JSON；保留值内的空格与引号。

公共参数与业务参数平铺在同一层。channel 是部分接口的业务字段，不是每个接口都必填；不需要用户 token，app_secret 和私钥始终留在你方服务器。

应用须具备接口调用权限。scope 使用小写接口标识，例如 open.ping/index、open.merchant/prepay；授权范围内的接口方可调用。

02 · 每次调用的固定流程

选择具体接口与业务参数 → 生成当前 timestamp 和全新 nonce → 合并公共参数与业务参数 → 计算 sign → 提交请求 → 同时检查 HTTP 状态码和 code。Ping 是联调自检，无需在每次业务请求前调用。

03 · 公共响应结构

{
  "code": 1,
  "msg": "提示信息",
  "time": "秒级时间戳字符串",
  "data": {}
}
字段类型必填说明
codeinteger是1 成功，0 失败。HTTP 状态码需独立判断。 取值：0 / 1。
msgstring是本次处理提示或失败原因；当前没有统一的细分业务错误码。
timestring是Unix 秒级时间戳，以字符串返回。
data按接口约定是业务数据，类型由具体接口定义；可能为对象、数组、字符串或 null。

data 的内容和类型由各接口单独定义，可能是对象、数组、字符串或 null。请先检查 code，再按对应接口说明处理 data。

04 · HTTP 与业务结果

HTTPcode含义
2001本次接口处理成功；申请受理不等于业务最终完成。
2000业务处理失败，请检查 msg 与 data。
4010公共参数、凭证、签名、IP、scope、时间戳或 nonce 校验失败。
5030服务暂不可用，请稍后重试；本次请求未受理。

05 · 复用公共客户端

下载 PHP 客户端并在你方服务器保存为 OpenApiClient.php。之后每个接口只需更换路径和业务参数；签名、时间戳、nonce、JSON 提交与响应解析统一处理。

下载公共 PHP 客户端 ↗ · 下载开放平台 OpenAPI 规范 ↗

<?php
require __DIR__ . '/OpenApiClient.php';
$client = new OpenApiClient('https://你的域名', '你的 app_id', '你的 app_secret');
$result = $client->request('/api/open.ping/index', ['echo' => 'hello']);
$httpStatus = $result['http_status'];
$body = $result['body'];
// 先检查 HTTP，再检查 $body['code']；业务结果在 $body['data']。

文件上传使用 multipart，文件内容不参与签名；地区查询的筛选值位于 URL，使用公共客户端的第三个 query 参数提交。

01

待签名串怎么拼

取本次请求的全部参数（公共 + 业务），按下面四步加工。两端任何一步不一致，都会落到「签名校验失败」。

① 剔除 sign 本身，以及值为 "" 或 null 的参数；0 是有效值，必须保留。

② 数组 / 对象值先序列化为 JSON 字符串（中文不转义、斜杠不转义），再参与拼接。

③ 全部键名按 ASCII 升序排列。

④ 拼成 k1=v1&k2=v2，字段之间用 & 连接，不做 URL 编码。

参与签名的是传输解码后的原始参数值，空格、引号和换行均保留；签名前不要裁剪空格、去除标签或做 HTML 转义。

待签名串单行字符串
app_id=ak_1f2e3d4c5b6a&channel=yibao&merchant={"mchName":"河南某某商贸有限公司","etpsAttr":"2"}&nonce=9f3c1a2b4d5e6f70&sign_type=HMAC-SHA256&timestamp=1786777149

签名串里的键序由 ASCII 升序决定，与你发送 JSON 时的书写顺序无关；但嵌套对象内部的键序会影响 JSON 字符串本身，建议固定字段顺序生成。

02

两条签名轨

HMAC-SHA256 用 app_secret 加签，适合快速对接；RSA2（SHA256withRSA）用你的私钥加签、平台用你登记的公钥验签，适合需要抗抵赖的正式接入。

HMAC-SHA256 · sign.phpPHP
function buildSignString(array $params): string
{
    unset($params['sign']);                 // ① 剔除 sign
    $filtered = [];
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) {
            continue;                       // ① 空值不参与签名（0 参与）
        }
        if (is_array($v)) {                 // ② 数组 / 对象转 JSON
            $v = json_encode($v, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        }
        $filtered[$k] = (string)$v;
    }
    ksort($filtered);                       // ③ 键名 ASCII 升序
    $pairs = [];
    foreach ($filtered as $k => $v) {
        $pairs[] = $k . '=' . $v;           // ④ k=v 拼接，不做 URL 编码
    }
    return implode('&', $pairs);
}

function sign(array $params, string $appSecret): array
{
    $params['timestamp'] = (string)time();
    $params['nonce'] = bin2hex(random_bytes(16));
    $params['sign'] = base64_encode(
        hash_hmac('sha256', buildSignString($params), $appSecret, true)
    );
    return $params;
}
RSA2 · sign.phpPHP openssl
// 私钥只放在你方服务器上，不随请求发送
$params['sign_type'] = 'RSA2';
$params['timestamp'] = (string)time();
$params['nonce'] = bin2hex(random_bytes(16));
$signStr = buildSignString($params);
$key     = openssl_pkey_get_private($yourPrivateKeyPem);

openssl_sign($signStr, $signature, $key, OPENSSL_ALGO_SHA256);
$params['sign'] = base64_encode($signature);

两条轨的差别只在最后一步算法，待签名串完全一致。切换签名方式后，记得同步更新 sign_type，否则会被判定为「不支持的签名方式」。

03

用 PHP cURL 先验证一次

签名逻辑写完后，先用 ping 打通链路，再进入业务接口联调。

ping.phpPOST JSON · HMAC-SHA256
<?php
$appSecret = '替换为你的 app_secret';
$params = [
    'app_id'    => '替换为你的 app_id',
    'sign_type' => 'HMAC-SHA256',
    'timestamp' => (string)time(),
    'nonce'     => bin2hex(random_bytes(16)),
    'echo'      => ' A&B 中文 ', // 原文参与签名，也会原样返回
];
ksort($params);
$pairs = [];
foreach ($params as $key => $value) {
    $pairs[] = $key . '=' . $value;
}
$params['sign'] = base64_encode(
    hash_hmac('sha256', implode('&', $pairs), $appSecret, true)
);

$ch = curl_init('https://你的域名/api/open.ping/index');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($params, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
]);
$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo 'HTTP ' . $httpStatus . PHP_EOL . $body;

在服务端 PHP 中运行，替换域名与应用凭证；不要把 app_secret 放进浏览器代码。示例每次生成当前时间戳和新 nonce，echo 也参与签名。

04

验签失败对照表

请核对公共参数类型、应用凭据、接口权限、时间戳、nonce 及签名。鉴权失败返回 HTTP 401，服务暂不可用返回 HTTP 503；响应体均为 { code: 0, msg, time, data: null }。

返回 msg可能原因HTTP
公共参数 XXX 类型不正确公共参数误传了数组或对象，应按参数表提交标量值401
app_id 不能为空未传 app_id，或传了空串401
应用不存在或已禁用app_id 拼错，或该应用已被停用401
IP 不在白名单内服务器出口 IP 与登记的白名单不一致（含 NAT 出口变化）401
该接口未授权所调接口不在该应用的 scope 授权范围内401
不支持的签名方式: XXXsign_type 与开通的签名方式不一致401
缺少签名 sign参数中没有 sign 字段401
timestamp 过期或非法服务器时间不准，或重试时沿用了旧时间戳401
缺少 nonce未传 nonce401
未配置接入方公钥使用 RSA2 前须登记你方应用公钥401
签名校验失败待签名串与平台不一致：空值未剔除、数组未转 JSON、键序不同、值被 URL 编码、密钥不匹配401
nonce 已使用过(疑似重放)同一 nonce 在 600 秒内被重复使用；每次请求及重试都应生成新 nonce401
防重放服务暂不可用，请稍后重试本次请求未受理；稍后使用新的 timestamp、nonce 和签名重试503

签名失败时，请核对实际发送的参数与待签名参数是否一致，并检查排序、空值、JSON 编码及应用凭据。

API Reference

接口清单

29 项接口参考，按需查看请求参数、调用示例、返回结果及通知要求。标记“暂未开放”的能力请先联系平台确认。

/api/open.ping/index 应用鉴权与原文回显

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用本接口验证应用凭据与签名。推荐 POST JSON，也支持 POST 表单或 GET；无需 channel，不会发起支付。

业务参数

参数类型必填 / 位置说明
echostring否按原文签名并原样返回；省略返回空字符串。显式 null、数组、对象、数字或布尔值不接受。 默认：""。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.ping/index
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "echo": "hello",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
echo 必须为字符串200将 echo 改为字符串，或者省略该字段。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "验签通过,连接正常",
  "time": "1792740000",
  "data": {
    "app_id": "ak_your_app_id",
    "app_name": "接入方名称",
    "pong": true,
    "echo": "hello"
  }
}

业务响应字段

字段类型必填说明
data.app_idstring是当前应用标识。
data.app_namestring是当前应用名称。
data.pongboolean是鉴权与本次处理成功时为 true。 取值：True。
data.echostring是原始字符串，缺省为空。
/api/open.merchant/register 提交商户进件

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

提交成功后保存 outMchNo，使用 registerQry 查询进件结果。code=1 表示申请已受理。

按主体类型提交完整资料：企业、个体提供营业执照资料，小微按对应要求提交身份和门店资料。

商户资料含特殊符号时，请先联系平台确认填写规范。

仅可操作或查询当前应用所属的商户和申请记录。

应用须先配置产品及约定费用；进件时逐项提交相同费用，不能加价或减价。示例费用仅作结构演示，请替换为所属应用各产品的当前配置；配置变化后请重新核对并提交。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
merchantobject是商户基本资料；数字及日期字段按字符串提交。
merchant.mchNamestring是商户全称。 最大 255 个字符。
merchant.mchNameAbbrstring是商户简称。 最大 255 个字符。
merchant.etpsAttrstring是主体类型：1 个体工商户，2 企业，3 小微。 取值：1 / 2 / 3。
merchant.servicePhonestring是客服电话，手机号或含区号的固定电话。
merchant.mccCodestring是三级行业项的 id，取 mccList 返回的 id/value；与返回的 mcc_code 字段区别。
merchant.contactNamestring是联系人姓名。 最大 255 个字符。
merchant.contactPhonestring是联系人电话。
merchant.contactEmailstring否联系人邮箱。
merchant.provinceCodestring条件注册地址省编码；企业/个体必填。
merchant.cityCodestring条件注册地址市编码；企业/个体必填。
merchant.districtCodestring条件注册地址区县编码；企业/个体必填。
merchant.provinceNamestring是注册地址省名称。
merchant.cityNamestring否注册地址市名称。
merchant.districtNamestring否注册地址区县名称。
merchant.addressRegstring是注册地址详细地址，2–255 字符。 最大 255 个字符。
merchant.longitudestring否经度。
merchant.latitudestring否纬度。
legalobject是法人资料。
legal.artifNamestring是法人姓名。
legal.artifCertifTypestring否证件类型，当前校验仅支持身份证 00。 取值：00。 默认："00"。
legal.artifCertifIdstring是法人身份证号。
legal.artifPhonestring是法人手机号。
legal.certifIdStartDatestring是有效期开始日期，YYYY-MM-DD。
legal.certifIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
business_licenseobject条件企业/个体需提供，小微可省略。
business_license.businessLicensestring是营业执照编号。
business_license.businessLicenseTypestring否证件类型，当前仅支持营业执照 01。 取值：01。
business_license.businessLicenseStartDatestring是营业执照有效期开始，YYYY-MM-DD。
business_license.businessLicenseEndDatestring是营业执照有效期结束，YYYY-MM-DD 或“长期”。
settlementobject是结算资料。
settlement.accountTypestring是0 对公账户，1 银行借记卡。 取值：0 / 1。
settlement.accountNostring是结算账户号，保留为字符串。
settlement.accountNamestring是结算账户户名。
settlement.certificateTypestring否结算人证件类型。 默认："00"。
settlement.certificateNostring是结算人证件号码。
settlement.settleTypestring否当前仅支持法人结算 1。 取值：1。
settlement.bankCodestring是总行编码，取 bankList.bank_code。
settlement.bankNamestring否总行名称；可由 bankCode 查询补齐，建议明确提交。
settlement.bankProvincestring否开户省编码。
settlement.bankProvinceNamestring否开户省名称。
settlement.bankCitystring否开户市编码。
settlement.bankCityNamestring否开户市名称。
settlement.subBankCodestring是支行联行号，取 branchList.branch_no。
settlement.subBankNamestring是支行名称。
settlement.mobileNostring是银行预留手机号。
channel_extraobject是经营地址与渠道扩展。
channel_extra.addressBussstring是经营详细地址，必填；必须放在 channel_extra，放入 merchant 会被丢弃。 最大 255 个字符。
channel_extra.busProvinceCodestring否经营地址省编码。
channel_extra.busProvinceNamestring是经营地址省名称。
channel_extra.busCityCodestring否经营地址市编码。
channel_extra.busCityNamestring是经营地址市名称。
channel_extra.busDistrictCodestring否经营地址区县编码。
channel_extra.busDistrictNamestring否经营地址区县名称。
channel_extra.shopTypestring否入网角色：0 连锁分店、1 总店、2 普通商户、3 分账接收方、4 平台商、5 入驻商户。 取值：0 / 1 / 2 / 3 / 4 / 5。
channel_extra.mchNameEnstring否商户英文名，填写时 2–255 字符。 最大 255 个字符。
uboarray条件受益人资料。企业需按进件资料要求提供，小微可传空数组。
ubo[].uboNamestring是受益人姓名。
ubo[].uboIdCardstring是受益人身份证号。
ubo[].uboIdStartDatestring是有效期开始日期，YYYY-MM-DD。
ubo[].uboIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
ubo[].uboPhonestring否受益人电话。
ubo[].uboAddressstring否受益人证件/联系地址。
ubo[].uboFrontPicLocalstring是身份证正面文件路径，取 upload 返回的 data.url。
ubo[].uboBackPicLocalstring是身份证反面文件路径，取 upload 返回的 data.url。
pathobject是按图片名称索引的对象，不是数组；具体图片必填条件需按商户资料清单确认。
path.legalFrontPicstring否法人身份证正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.legalBackPicstring否法人身份证反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.businessLicensePicstring否营业执照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopGatePicstring否门头照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopInsidePicstring否店内照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.cashierDeskPicstring否收银台照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardPicstring否银行卡正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardBackPicstring否银行卡反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankAccountPermitPicstring否开户许可证文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shareCertificatestring否分账证明文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
callbackurlstring是进件结果通知地址，不接收通知时请保留该字段并填写空字符串。
parentMerchantstring否上级商户号。
productCodesarray否进件产品代码列表，仅可选择所属应用已配置的产品；省略时使用应用全部产品。每个所选产品均须在 productRates 填写与应用当前配置相等的费用。支付方式与场景须对应所选产品；支付宝 H5_PAY 对应 H5_PAY_M_ALIPAY_OFFLINE。最终开通结果以进件结果为准。
productRatesobject是所选产品的约定费用，按产品代码索引。每个选中产品必须填写一个十进制字符串，且等于所属应用当前配置，暂不允许加价或减价。不得遗漏所选产品或填写未选产品；百分比按 % 填写，固定费用按元/笔填写，零元也须显式填写。省略 productCodes 时，须填写应用全部产品的费用。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/register
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchant": {
    "mchName": "河南某某商贸有限公司",
    "mchNameAbbr": "某某商贸",
    "etpsAttr": "2",
    "servicePhone": "0371-88886666",
    "mccCode": "12",
    "contactName": "张三",
    "contactPhone": "13800138000",
    "contactEmail": "zhangsan@example.com",
    "provinceCode": "410000",
    "cityCode": "410100",
    "districtCode": "410102",
    "provinceName": "河南省",
    "cityName": "郑州市",
    "districtName": "中原区",
    "addressReg": "某某街道 100 号 3 层",
    "longitude": "113.62",
    "latitude": "34.75"
  },
  "legal": {
    "artifName": "张三",
    "artifCertifType": "00",
    "artifCertifId": "410000199001011234",
    "artifPhone": "13800138000",
    "certifIdStartDate": "2015-01-01",
    "certifIdEndDate": "2035-01-01"
  },
  "business_license": {
    "businessLicense": "91410100MA3XXXXXXX",
    "businessLicenseType": "01",
    "businessLicenseStartDate": "2019-06-01",
    "businessLicenseEndDate": "2039-06-01"
  },
  "settlement": {
    "accountType": "0",
    "accountNo": "6222021234567890123",
    "accountName": "河南某某商贸有限公司",
    "certificateType": "00",
    "certificateNo": "410000199001011234",
    "settleType": "1",
    "bankCode": "ABC",
    "bankName": "中国农业银行",
    "subBankCode": "103491000018",
    "subBankName": "中国农业银行郑州中原支行",
    "mobileNo": "13800138000",
    "bankProvince": "410000",
    "bankProvinceName": "河南省",
    "bankCity": "410100",
    "bankCityName": "郑州市"
  },
  "ubo": [
    {
      "uboName": "张三",
      "uboIdCard": "410000199001011234",
      "uboIdStartDate": "2015-01-01",
      "uboIdEndDate": "2035-01-01",
      "uboPhone": "13800138000",
      "uboAddress": "河南省郑州市中原区某某街道 100 号",
      "uboFrontPicLocal": "/uploads/20260929/legal_front.jpg",
      "uboBackPicLocal": "/uploads/20260929/legal_back.jpg"
    }
  ],
  "path": {
    "legalFrontPic": "/uploads/20260929/legal_front.jpg",
    "legalBackPic": "/uploads/20260929/legal_back.jpg",
    "businessLicensePic": "/uploads/20260929/license.jpg",
    "shopGatePic": "/uploads/20260929/gate.jpg",
    "shopInsidePic": "/uploads/20260929/inside.jpg",
    "bankCardPic": "/uploads/20260929/bank.jpg",
    "bankCardBackPic": "/uploads/20261023/bankBack.jpg",
    "bankAccountPermitPic": "/uploads/20261023/permit.jpg"
  },
  "callbackurl": "https://your-domain.com/notify/merchant",
  "channel_extra": {
    "addressBuss": "某某街道 100 号 3 层",
    "busProvinceCode": "410000",
    "busProvinceName": "河南省",
    "busCityCode": "410100",
    "busCityName": "郑州市",
    "busDistrictCode": "410102",
    "busDistrictName": "中原区",
    "shopType": "2"
  },
  "sign": "由公共客户端计算",
  "productCodes": [
    "USER_SCAN_WECHAT_OFFLINE",
    "D1_MANUAL",
    "EASYSHARE_SHARE_MERCHANT"
  ],
  "productRates": {
    "USER_SCAN_WECHAT_OFFLINE": "0.72",
    "D1_MANUAL": "0.00",
    "EASYSHARE_SHARE_MERCHANT": "0.02"
  }
}

业务错误与处理

msg / 情况HTTP处理说明
请选择渠道200提交 channel=yibao。
申请失败，参数错误：…200根据提示补齐对应分组字段。
进件申请失败: …200先查询并核对原申请状态，再根据返回提示处理。
请先为应用配置进件产品和约定费用200由应用管理方先配置可用产品与费用后再提交进件。
productRates 必须逐项填写所选产品的约定费用，不能缺少或多填200productRates 的键须与所选产品一一对应；未选产品不要提交。
productRates 中每个所选产品必须填写十进制费用字符串200每项费用使用最多四位小数的非负十进制字符串；固定零费用填写 "0"。
…费用必须等于所属应用当前配置 …200逐项核对当前应用配置，不能加价或减价；应用已调价时重新取得配置后提交。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {
    "outMchNo": "yibao_example_request"
  }
}

业务响应字段

字段类型必填说明
data.outMchNostring是进件请求号，用于 registerQry/update/modifyMerchant。
/api/open.merchant/mccList 行业类目查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

按层级查询行业目录；进件时使用三级目录项 id。当前不支持 mercType 筛选。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
levelstring否层级：1 一级，2 二级，3 三级。 取值：1 / 2 / 3。 默认："1"。
fatherCodestring否父级项 id，取上一级响应的 id/value。
mccCodestring否按字典的 mcc_code 精确筛选。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/mccList
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "level": "1",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
不支持的渠道200当前使用 yibao。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": [
    {
      "id": 1,
      "mcc_name": "零售业",
      "pid": 0,
      "level": 1,
      "mcc_code": 0,
      "value": 1,
      "name": "零售业"
    }
  ]
}

业务响应字段

字段类型必填说明
data[].idinteger / string否行业目录项 id；进件使用三级项 id。
data[].mcc_codestring / integer否行业编码；进件填写三级项 id，不能与此字段混用。
data[].mcc_namestring否行业名称。
data[].levelinteger / string否层级。
data[].pidinteger / string否父级项 id。
data[].valueinteger / string否与 id 一致。
data[].namestring否与 mcc_name 一致。
/api/open.merchant/areaCode 地区编码查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

channel 与公共参数放入 JSON 正文，areaLevel、parentCode 放入 URL；两处参数一起参与签名，可使用公共客户端的第三个 query 参数。

当前使用 areaLevel、parentCode 查询；不支持按地区名称或批量地区编码筛选。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
areaLevelstring否 / URL当前只读取 URL 查询参数。1 省、2 市、3 区县。
parentCodestring否 / URL父级编码；填写时必须同时提供 areaLevel，查市用 2，查区县用 3。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/areaCode?areaLevel=2&parentCode=410000
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
不支持的渠道200正文提交 channel=yibao。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": [
    {
      "code": "110000",
      "value": "110000",
      "name": "北京市",
      "level": 1
    }
  ]
}

业务响应字段

字段类型必填说明
data[].codestring否地区编码。
data[].valuestring否与 code 一致。
data[].namestring否地区名称。
data[].levelinteger / string否地区层级。
/api/open.merchant/bankList 银行列表查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

返回银行列表；需要名称搜索时，在返回列表中筛选。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
bankCodestring否银行编码，精确匹配。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/bankList
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "bankCode": "ABC",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
不支持的渠道200使用 yibao。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": [
    {
      "bank_code": "ABC",
      "value": "ABC",
      "name": "中国农业银行",
      "bank_no": "103100000026"
    }
  ]
}

业务响应字段

字段类型必填说明
data[].bank_codestring否银行编码，填入 settlement.bankCode。
data[].valuestring否与 bank_code 一致。
data[].namestring否银行名称。
data[].bank_nostring否银行联行号。
/api/open.merchant/branchList 支行 / 网点查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

可按省市编码、银行编码查询联行号；当前不支持 keyword 名称筛选。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
bankCodestring否银行总行编码。
provinceCodestring否省编码。
cityCodestring否市编码。
branchNostring否支行联行号，精确匹配。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/branchList
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "bankCode": "ABC",
  "cityCode": "410100",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
不支持的渠道200使用 yibao。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": [
    {
      "branch_no": "102100000021",
      "branch_name": "中国工商银行北京分行营业部",
      "value": "102100000021-中国工商银行北京分行营业部",
      "name": "中国工商银行北京分行营业部"
    }
  ]
}

业务响应字段

字段类型必填说明
data[].branch_nostring否支行联行号，填入 settlement.subBankCode。
data[].branch_namestring否支行名称。
data[].valuestring否branch_no 与 branch_name 以短横线连接。
data[].namestring否与 branch_name 一致。
/api/open.merchant/upload 资料图片上传

POSTContent-Type multipart/form-data公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用 multipart/form-data 提交文件，公共参数作为表单字段；文件内容不参与签名。

上传成功后保存返回的文件地址，用于提交商户资料。

业务参数

参数类型必填 / 位置说明
filefile是文件字段固定为 file；文件内容不参与签名。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

curl 'https://你的域名/api/open.merchant/upload' \
  -F 'app_id=ak_your_app_id' \
  -F 'sign_type=HMAC-SHA256' \
  -F 'timestamp=运行时生成' \
  -F 'nonce=每次请求生成新随机串' \
  -F 'file=@/你的本地路径/legal_front.jpg' \
  -F 'sign=由公共客户端计算'

业务错误与处理

msg / 情况HTTP处理说明
请上传文件200确认 multipart 的文件字段名为 file。
文件上传失败…200核对文件大小、类型和实际错误提示。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "上传成功",
  "time": "1792740000",
  "data": {
    "url": "/uploads/20261023/legal_front.jpg"
  }
}

业务响应字段

字段类型必填说明
data.urlstring是上传成功后的文件路径，填入进件 path 对应图片字段。
/api/open.merchant/update 驳回后修改进件资料

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

用于修改已驳回的进件申请。请提交完整资料，审核中及待签约状态不支持修改。

callbackurl 不接收通知时填写空字符串；ubo 没有资料时保留为空数组。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
merchantobject是商户基本资料；数字及日期字段按字符串提交。
merchant.mchNamestring是商户全称。 最大 255 个字符。
merchant.mchNameAbbrstring是商户简称。 最大 255 个字符。
merchant.etpsAttrstring是主体类型：1 个体工商户，2 企业，3 小微。 取值：1 / 2 / 3。
merchant.servicePhonestring是客服电话，手机号或含区号的固定电话。
merchant.mccCodestring是三级行业项的 id，取 mccList 返回的 id/value；与返回的 mcc_code 字段区别。
merchant.contactNamestring是联系人姓名。 最大 255 个字符。
merchant.contactPhonestring是联系人电话。
merchant.contactEmailstring否联系人邮箱。
merchant.provinceCodestring条件注册地址省编码；企业/个体必填。
merchant.cityCodestring条件注册地址市编码；企业/个体必填。
merchant.districtCodestring条件注册地址区县编码；企业/个体必填。
merchant.provinceNamestring是注册地址省名称。
merchant.cityNamestring否注册地址市名称。
merchant.districtNamestring否注册地址区县名称。
merchant.addressRegstring是注册地址详细地址，2–255 字符。 最大 255 个字符。
merchant.longitudestring否经度。
merchant.latitudestring否纬度。
legalobject是法人资料。
legal.artifNamestring是法人姓名。
legal.artifCertifTypestring否证件类型，当前校验仅支持身份证 00。 取值：00。 默认："00"。
legal.artifCertifIdstring是法人身份证号。
legal.artifPhonestring是法人手机号。
legal.certifIdStartDatestring是有效期开始日期，YYYY-MM-DD。
legal.certifIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
business_licenseobject条件企业/个体需提供，小微可省略。
business_license.businessLicensestring是营业执照编号。
business_license.businessLicenseTypestring否证件类型，当前仅支持营业执照 01。 取值：01。
business_license.businessLicenseStartDatestring是营业执照有效期开始，YYYY-MM-DD。
business_license.businessLicenseEndDatestring是营业执照有效期结束，YYYY-MM-DD 或“长期”。
settlementobject是结算资料。
settlement.accountTypestring是0 对公账户，1 银行借记卡。 取值：0 / 1。
settlement.accountNostring是结算账户号，保留为字符串。
settlement.accountNamestring是结算账户户名。
settlement.certificateTypestring否结算人证件类型。 默认："00"。
settlement.certificateNostring是结算人证件号码。
settlement.settleTypestring否当前仅支持法人结算 1。 取值：1。
settlement.bankCodestring是总行编码，取 bankList.bank_code。
settlement.bankNamestring否总行名称；可由 bankCode 查询补齐，建议明确提交。
settlement.bankProvincestring否开户省编码。
settlement.bankProvinceNamestring否开户省名称。
settlement.bankCitystring否开户市编码。
settlement.bankCityNamestring否开户市名称。
settlement.subBankCodestring是支行联行号，取 branchList.branch_no。
settlement.subBankNamestring是支行名称。
settlement.mobileNostring是银行预留手机号。
channel_extraobject是经营地址与渠道扩展。
channel_extra.addressBussstring是经营详细地址，必填；必须放在 channel_extra，放入 merchant 会被丢弃。 最大 255 个字符。
channel_extra.busProvinceCodestring否经营地址省编码。
channel_extra.busProvinceNamestring是经营地址省名称。
channel_extra.busCityCodestring否经营地址市编码。
channel_extra.busCityNamestring是经营地址市名称。
channel_extra.busDistrictCodestring否经营地址区县编码。
channel_extra.busDistrictNamestring否经营地址区县名称。
channel_extra.shopTypestring否入网角色：0 连锁分店、1 总店、2 普通商户、3 分账接收方、4 平台商、5 入驻商户。 取值：0 / 1 / 2 / 3 / 4 / 5。
channel_extra.mchNameEnstring否商户英文名，填写时 2–255 字符。 最大 255 个字符。
uboarray是，可为空数组受益人资料。企业需按进件资料要求提供，小微可传空数组。
ubo[].uboNamestring是受益人姓名。
ubo[].uboIdCardstring是受益人身份证号。
ubo[].uboIdStartDatestring是有效期开始日期，YYYY-MM-DD。
ubo[].uboIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
ubo[].uboPhonestring否受益人电话。
ubo[].uboAddressstring否受益人证件/联系地址。
ubo[].uboFrontPicLocalstring是身份证正面文件路径，取 upload 返回的 data.url。
ubo[].uboBackPicLocalstring是身份证反面文件路径，取 upload 返回的 data.url。
pathobject是按图片名称索引的对象，不是数组；具体图片必填条件需按商户资料清单确认。
path.legalFrontPicstring否法人身份证正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.legalBackPicstring否法人身份证反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.businessLicensePicstring否营业执照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopGatePicstring否门头照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopInsidePicstring否店内照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.cashierDeskPicstring否收银台照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardPicstring否银行卡正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardBackPicstring否银行卡反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankAccountPermitPicstring否开户许可证文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shareCertificatestring否分账证明文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
callbackurlstring是进件结果通知地址，不接收通知时请保留该字段并填写空字符串。
parentMerchantstring否上级商户号。
outMchNostring是register 返回的进件请求号。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/update
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchant": {
    "mchName": "河南某某商贸有限公司",
    "mchNameAbbr": "某某商贸",
    "etpsAttr": "2",
    "servicePhone": "0371-88886666",
    "mccCode": "12",
    "contactName": "张三",
    "contactPhone": "13800138000",
    "contactEmail": "zhangsan@example.com",
    "provinceCode": "410000",
    "cityCode": "410100",
    "districtCode": "410102",
    "provinceName": "河南省",
    "cityName": "郑州市",
    "districtName": "中原区",
    "addressReg": "某某街道 100 号 3 层",
    "longitude": "113.62",
    "latitude": "34.75"
  },
  "legal": {
    "artifName": "张三",
    "artifCertifType": "00",
    "artifCertifId": "410000199001011234",
    "artifPhone": "13800138000",
    "certifIdStartDate": "2015-01-01",
    "certifIdEndDate": "2035-01-01"
  },
  "business_license": {
    "businessLicense": "91410100MA3XXXXXXX",
    "businessLicenseType": "01",
    "businessLicenseStartDate": "2019-06-01",
    "businessLicenseEndDate": "2039-06-01"
  },
  "settlement": {
    "accountType": "0",
    "accountNo": "6222021234567890123",
    "accountName": "河南某某商贸有限公司",
    "certificateType": "00",
    "certificateNo": "410000199001011234",
    "settleType": "1",
    "bankCode": "ABC",
    "bankName": "中国农业银行",
    "subBankCode": "103491000018",
    "subBankName": "中国农业银行郑州中原支行",
    "mobileNo": "13800138000",
    "bankProvince": "410000",
    "bankProvinceName": "河南省",
    "bankCity": "410100",
    "bankCityName": "郑州市"
  },
  "ubo": [
    {
      "uboName": "张三",
      "uboIdCard": "410000199001011234",
      "uboIdStartDate": "2015-01-01",
      "uboIdEndDate": "2035-01-01",
      "uboPhone": "13800138000",
      "uboAddress": "河南省郑州市中原区某某街道 100 号",
      "uboFrontPicLocal": "/uploads/20260929/legal_front.jpg",
      "uboBackPicLocal": "/uploads/20260929/legal_back.jpg"
    }
  ],
  "path": {
    "legalFrontPic": "/uploads/20260929/legal_front.jpg",
    "legalBackPic": "/uploads/20260929/legal_back.jpg",
    "businessLicensePic": "/uploads/20260929/license.jpg",
    "shopGatePic": "/uploads/20260929/gate.jpg",
    "shopInsidePic": "/uploads/20260929/inside.jpg",
    "bankCardPic": "/uploads/20260929/bank.jpg",
    "bankCardBackPic": "/uploads/20261023/bankBack.jpg",
    "bankAccountPermitPic": "/uploads/20261023/permit.jpg"
  },
  "callbackurl": "https://your-domain.com/notify/merchant",
  "channel_extra": {
    "addressBuss": "某某街道 100 号 3 层",
    "busProvinceCode": "410000",
    "busProvinceName": "河南省",
    "busCityCode": "410100",
    "busCityName": "郑州市",
    "busDistrictCode": "410102",
    "busDistrictName": "中原区",
    "shopType": "2"
  },
  "outMchNo": "yibao_example_request",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
进件信息不存在200核对 outMchNo。
该状态进件信息不能修改！200确认原申请已驳回。
申请失败，参数错误：…200补齐完整进件资料。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": "成功"
}

业务响应字段

字段类型必填说明
datastring—操作成功时返回字符串“成功”。
/api/open.merchant/modifyMerchant 成功后变更商户资料

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

商户进件成功后方可变更资料。提交完整资料，ubo、path 无数据时也应保留字段。

资料变更需先联系平台确认可用申请信息；获得 requestNo 后使用 modifyQry 查询进度。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
merchantobject是商户基本资料；数字及日期字段按字符串提交。
merchant.mchNamestring是商户全称。 最大 255 个字符。
merchant.mchNameAbbrstring是商户简称。 最大 255 个字符。
merchant.etpsAttrstring是主体类型：1 个体工商户，2 企业，3 小微。 取值：1 / 2 / 3。
merchant.servicePhonestring是客服电话，手机号或含区号的固定电话。
merchant.mccCodestring是三级行业项的 id，取 mccList 返回的 id/value；与返回的 mcc_code 字段区别。
merchant.contactNamestring是联系人姓名。 最大 255 个字符。
merchant.contactPhonestring是联系人电话。
merchant.contactEmailstring否联系人邮箱。
merchant.provinceCodestring条件注册地址省编码；企业/个体必填。
merchant.cityCodestring条件注册地址市编码；企业/个体必填。
merchant.districtCodestring条件注册地址区县编码；企业/个体必填。
merchant.provinceNamestring是注册地址省名称。
merchant.cityNamestring否注册地址市名称。
merchant.districtNamestring否注册地址区县名称。
merchant.addressRegstring是注册地址详细地址，2–255 字符。 最大 255 个字符。
merchant.longitudestring否经度。
merchant.latitudestring否纬度。
legalobject是法人资料。
legal.artifNamestring是法人姓名。
legal.artifCertifTypestring否证件类型，当前校验仅支持身份证 00。 取值：00。 默认："00"。
legal.artifCertifIdstring是法人身份证号。
legal.artifPhonestring是法人手机号。
legal.certifIdStartDatestring是有效期开始日期，YYYY-MM-DD。
legal.certifIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
business_licenseobject条件企业/个体需提供，小微可省略。
business_license.businessLicensestring是营业执照编号。
business_license.businessLicenseTypestring否证件类型，当前仅支持营业执照 01。 取值：01。
business_license.businessLicenseStartDatestring是营业执照有效期开始，YYYY-MM-DD。
business_license.businessLicenseEndDatestring是营业执照有效期结束，YYYY-MM-DD 或“长期”。
settlementobject是结算资料。
settlement.accountTypestring是0 对公账户，1 银行借记卡。 取值：0 / 1。
settlement.accountNostring是结算账户号，保留为字符串。
settlement.accountNamestring是结算账户户名。
settlement.certificateTypestring否结算人证件类型。 默认："00"。
settlement.certificateNostring是结算人证件号码。
settlement.settleTypestring否当前仅支持法人结算 1。 取值：1。
settlement.bankCodestring是总行编码，取 bankList.bank_code。
settlement.bankNamestring否总行名称；可由 bankCode 查询补齐，建议明确提交。
settlement.bankProvincestring否开户省编码。
settlement.bankProvinceNamestring否开户省名称。
settlement.bankCitystring否开户市编码。
settlement.bankCityNamestring否开户市名称。
settlement.subBankCodestring是支行联行号，取 branchList.branch_no。
settlement.subBankNamestring是支行名称。
settlement.mobileNostring是银行预留手机号。
channel_extraobject是经营地址与渠道扩展。
channel_extra.addressBussstring是经营详细地址，必填；必须放在 channel_extra，放入 merchant 会被丢弃。 最大 255 个字符。
channel_extra.busProvinceCodestring否经营地址省编码。
channel_extra.busProvinceNamestring是经营地址省名称。
channel_extra.busCityCodestring否经营地址市编码。
channel_extra.busCityNamestring是经营地址市名称。
channel_extra.busDistrictCodestring否经营地址区县编码。
channel_extra.busDistrictNamestring否经营地址区县名称。
channel_extra.shopTypestring否入网角色：0 连锁分店、1 总店、2 普通商户、3 分账接收方、4 平台商、5 入驻商户。 取值：0 / 1 / 2 / 3 / 4 / 5。
channel_extra.mchNameEnstring否商户英文名，填写时 2–255 字符。 最大 255 个字符。
uboarray条件受益人资料。企业需按进件资料要求提供，小微可传空数组。
ubo[].uboNamestring是受益人姓名。
ubo[].uboIdCardstring是受益人身份证号。
ubo[].uboIdStartDatestring是有效期开始日期，YYYY-MM-DD。
ubo[].uboIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
ubo[].uboPhonestring否受益人电话。
ubo[].uboAddressstring否受益人证件/联系地址。
ubo[].uboFrontPicLocalstring是身份证正面文件路径，取 upload 返回的 data.url。
ubo[].uboBackPicLocalstring是身份证反面文件路径，取 upload 返回的 data.url。
pathobject是按图片名称索引的对象，不是数组；具体图片必填条件需按商户资料清单确认。
path.legalFrontPicstring否法人身份证正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.legalBackPicstring否法人身份证反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.businessLicensePicstring否营业执照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopGatePicstring否门头照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shopInsidePicstring否店内照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.cashierDeskPicstring否收银台照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardPicstring否银行卡正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankCardBackPicstring否银行卡反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.bankAccountPermitPicstring否开户许可证文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
path.shareCertificatestring否分账证明文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。
outMchNostring是已进件成功的商户请求号。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/modifyMerchant
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchant": {
    "mchName": "河南某某商贸有限公司",
    "mchNameAbbr": "某某商贸",
    "etpsAttr": "2",
    "servicePhone": "0371-88886666",
    "mccCode": "12",
    "contactName": "张三",
    "contactPhone": "13800138000",
    "contactEmail": "zhangsan@example.com",
    "provinceCode": "410000",
    "cityCode": "410100",
    "districtCode": "410102",
    "provinceName": "河南省",
    "cityName": "郑州市",
    "districtName": "中原区",
    "addressReg": "某某街道 100 号 3 层",
    "longitude": "113.62",
    "latitude": "34.75"
  },
  "legal": {
    "artifName": "张三",
    "artifCertifType": "00",
    "artifCertifId": "410000199001011234",
    "artifPhone": "13800138000",
    "certifIdStartDate": "2015-01-01",
    "certifIdEndDate": "2035-01-01"
  },
  "business_license": {
    "businessLicense": "91410100MA3XXXXXXX",
    "businessLicenseType": "01",
    "businessLicenseStartDate": "2019-06-01",
    "businessLicenseEndDate": "2039-06-01"
  },
  "settlement": {
    "accountType": "0",
    "accountNo": "6222021234567890123",
    "accountName": "河南某某商贸有限公司",
    "certificateType": "00",
    "certificateNo": "410000199001011234",
    "settleType": "1",
    "bankCode": "ABC",
    "bankName": "中国农业银行",
    "subBankCode": "103491000018",
    "subBankName": "中国农业银行郑州中原支行",
    "mobileNo": "13800138000",
    "bankProvince": "410000",
    "bankProvinceName": "河南省",
    "bankCity": "410100",
    "bankCityName": "郑州市"
  },
  "ubo": [
    {
      "uboName": "张三",
      "uboIdCard": "410000199001011234",
      "uboIdStartDate": "2015-01-01",
      "uboIdEndDate": "2035-01-01",
      "uboPhone": "13800138000",
      "uboAddress": "河南省郑州市中原区某某街道 100 号",
      "uboFrontPicLocal": "/uploads/20260929/legal_front.jpg",
      "uboBackPicLocal": "/uploads/20260929/legal_back.jpg"
    }
  ],
  "path": {
    "legalFrontPic": "/uploads/20260929/legal_front.jpg",
    "legalBackPic": "/uploads/20260929/legal_back.jpg",
    "businessLicensePic": "/uploads/20260929/license.jpg",
    "shopGatePic": "/uploads/20260929/gate.jpg",
    "shopInsidePic": "/uploads/20260929/inside.jpg",
    "bankCardPic": "/uploads/20260929/bank.jpg",
    "bankCardBackPic": "/uploads/20261023/bankBack.jpg",
    "bankAccountPermitPic": "/uploads/20261023/permit.jpg"
  },
  "channel_extra": {
    "addressBuss": "某某街道 100 号 3 层",
    "busProvinceCode": "410000",
    "busProvinceName": "河南省",
    "busCityCode": "410100",
    "busCityName": "郑州市",
    "busDistrictCode": "410102",
    "busDistrictName": "中原区",
    "shopType": "2"
  },
  "outMchNo": "yibao_example_request",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
当前商户未进件成功无法申请商户资料变更200先查询原进件状态。
修改失败: …200核对提交资料及返回提示。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {
    "applicationNo": "渠道变更申请单号",
    "applicationStatus": "渠道状态值"
  }
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data.applicationNostring是资料变更申请单号，与查询时使用的 requestNo 不同。
data.applicationStatusstring是资料变更申请的处理状态。
/api/open.merchant/modifyQry 资料变更进度查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用资料变更时取得的 requestNo 查询，不能使用原进件 outMchNo。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
requestNostring是变更请求号，不是原进件 outMchNo。须先与平台确认该号码的获取方式。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/modifyQry
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "requestNo": "YIBAO_MODIFY_example",
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {}
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data按渠道返回—业务处理结果，具体字段须在接入前确认。
/api/open.merchant/registerQry 进件进度查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用进件申请返回的 outMchNo 作为 requestNo 查询进度。

申请尚未完成时，主要返回 applicationStatus、auditOpinion、requestNo；成功后可取得用于收款的 merchantNo。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
requestNostring是register 返回的 outMchNo；此接口的入参字段名叫 requestNo。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/registerQry
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "requestNo": "yibao_example_request",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
入网请求号不能为空200提供 requestNo。
您未发起该请求号对应的入网申请,请核实200核对原进件返回的 outMchNo。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {
    "applicationStatus": 1,
    "auditOpinion": "",
    "requestNo": "yibao_example_request",
    "merchantNo": "10093518558",
    "elecSignUrl": "",
    "intentionAuthUrl": ""
  }
}

业务响应字段

字段类型必填说明
data.applicationStatusinteger / string是进件状态：-1 待完善、0 待审核、1 成功、2 驳回、3 转人工、4 真实性待验证、5 待签合同、6 业务开通中；不是按数字大小推进。
data.auditOpinionstring / null是审核意见或驳回原因。
data.requestNostring是对应 register 返回的 outMchNo。
data.merchantNostring / null否进件成功后返回的商户号，用于支付。
data.elecSignUrlstring / null否合同签署地址。
data.intentionAuthUrlstring / null否真实性验证地址。
/api/open.merchant/merchantStatusQry 暂未开放渠道商户状态查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

此接口暂未开放正式接入。查询进件结果请使用 registerQry。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
mchNostring是商户号，对应 registerQry 返回的 merchantNo。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/merchantStatusQry
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "mchNo": "10093518558",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
商户号不能为空200提供 mchNo。
响应不是有效 JSON200此接口暂未开放，请使用 registerQry 查询进件结果。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {}
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data按渠道返回—业务处理结果，具体字段须在接入前确认。
/api/open.merchant/channels 可用渠道列表

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

查询当前可用的收款通道标识；无需业务参数，按公共协议签名调用。

业务参数

无业务参数，仅提交公共参数。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/channels
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "success",
  "time": "1792740000",
  "data": {
    "yibao": "易宝"
  }
}

业务响应字段

字段类型必填说明
data.yibaostring是易宝渠道显示名称。
/api/open.merchant/wechatAuthApply 微信实名认证申请

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

此功能需平台协助开通。调用前请联系平台确认商户 id、图片资源标识及所需商户资料。

按本接口要求平铺提交字段，不使用 register 的嵌套分组；pics 使用已确认的资源标识。

保存申请返回的 applymentId，作为后续认证查询的 applyNo。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
mchNostring是商户号。
idinteger是商户记录标识，调用前联系平台获取并确认。
etpsAttrstring是主体类型。 取值：1 / 2 / 3。
artifPhonestring是法人手机号。
certifIdStartDatestring是有效期开始日期，YYYY-MM-DD。
certifIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
provinceNamestring是省名称。
cityNamestring是市名称。
districtNamestring是区县名称。
addressRegstring是详细地址。
businessLicenseStartDatestring是执照开始日期。
businessLicenseEndDatestring是执照结束日期或“长期”。
picsobject是
pics.03string是证照资源标识；请在调用前确认所需资源标识，不可使用 upload 返回的文件路径代替。
pics.05string小微条件小微门头照片的渠道资源标识。
pics.04string小微条件小微店内照片的渠道资源标识。
mchNamestring小微条件小微门店名。
busCityCodestring小微条件小微经营地址市编码。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/wechatAuthApply
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "mchNo": "10093518558",
  "id": 123,
  "etpsAttr": "2",
  "artifPhone": "13800138000",
  "certifIdStartDate": "2015-01-01",
  "certifIdEndDate": "2035-01-01",
  "provinceName": "河南省",
  "cityName": "郑州市",
  "districtName": "中原区",
  "addressReg": "某某街道 100 号 3 层",
  "businessLicenseStartDate": "2019-06-01",
  "businessLicenseEndDate": "2039-06-01",
  "pics": {
    "03": "渠道证照资源标识"
  },
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {
    "applymentId": "渠道申请单号"
  }
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data.applymentIdstring是认证申请单号；后续认证查询时作为 applyNo 提交。
/api/open.merchant/alipayAuthApply 支付宝实名认证申请

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

此功能需平台协助开通。调用前请联系平台确认商户 id、图片资源标识及所需商户资料。

按本接口要求平铺提交字段，不使用 register 的嵌套分组；pics 使用已确认的资源标识。

保存申请返回的 applymentId，作为后续认证查询的 applyNo。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
mchNostring是商户号。
idinteger是商户记录标识，调用前联系平台获取并确认。
etpsAttrstring是主体类型。 取值：1 / 2 / 3。
artifPhonestring是法人手机号。
certifIdStartDatestring是有效期开始日期，YYYY-MM-DD。
certifIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
provinceNamestring是省名称。
cityNamestring是市名称。
districtNamestring是区县名称。
addressRegstring是详细地址。
businessLicenseStartDatestring是执照开始日期。
businessLicenseEndDatestring是执照结束日期或“长期”。
picsobject小微条件
pics.05string小微条件小微门头照片的渠道资源标识。
pics.04string小微条件小微店内照片的渠道资源标识。
mchNamestring小微条件小微门店名。
busCityCodestring小微条件小微经营地址市编码。
artifCertifTypestring是法人证件类型。
businessLicensestring是营业执照编号。
uboInfoListarray是此申请使用 uboInfoList，不是 register 的 ubo；图片使用渠道资源标识。
uboInfoList[].uboNamestring是受益人姓名。
uboInfoList[].uboIdCardstring是受益人证件号。
uboInfoList[].uboFrontPicstring是正面渠道图片标识。
uboInfoList[].uboBackPicstring是反面渠道图片标识。
uboInfoList[].uboAddressstring是受益人地址。
uboInfoList[].uboIdStartDatestring是有效期开始日期，YYYY-MM-DD。
uboInfoList[].uboIdEndDatestring是有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。
busProvinceCodestring小微条件小微经营省编码。
busDistrictCodestring小微条件小微经营区县编码。
addressBussstring小微条件小微经营详细地址。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/alipayAuthApply
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "mchNo": "10093518558",
  "id": 123,
  "etpsAttr": "2",
  "artifPhone": "13800138000",
  "certifIdStartDate": "2015-01-01",
  "certifIdEndDate": "2035-01-01",
  "provinceName": "河南省",
  "cityName": "郑州市",
  "districtName": "中原区",
  "addressReg": "某某街道 100 号 3 层",
  "businessLicenseStartDate": "2019-06-01",
  "businessLicenseEndDate": "2039-06-01",
  "artifCertifType": "00",
  "businessLicense": "91410100MA3XXXXXXX",
  "uboInfoList": [
    {
      "uboName": "张三",
      "uboIdCard": "410000199001011234",
      "uboFrontPic": "渠道受益人正面资源",
      "uboBackPic": "渠道受益人反面资源",
      "uboAddress": "河南省郑州市中原区某某街道",
      "uboIdStartDate": "2015-01-01",
      "uboIdEndDate": "2035-01-01"
    }
  ],
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {
    "applymentId": "渠道申请单号"
  }
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data.applymentIdstring是认证申请单号；后续认证查询时作为 applyNo 提交。
/api/open.merchant/wechatAuthQry 微信实名认证状态查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用认证申请返回的申请单号查询认证结果。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
applyNostring是申请受理结果中的 applymentId；本接口入参名为 applyNo。
mchNostring是商户号。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/wechatAuthQry
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "applyNo": "渠道申请单号",
  "mchNo": "10093518558",
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {}
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data按渠道返回—业务处理结果，具体字段须在接入前确认。
/api/open.merchant/alipayAuthQry 支付宝实名认证状态查询

POSTContent-Type application/json公共协议 ↗

公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。

使用认证申请返回的申请单号查询认证结果。

仅可操作或查询当前应用所属的商户和申请记录。

业务参数

参数类型必填 / 位置说明
channelstring是开放平台文档约定的渠道。 取值：yibao。
applyNostring是申请受理结果中的 applymentId；本接口入参名为 applyNo。
mchNostring是商户号。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/alipayAuthQry
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "applyNo": "渠道申请单号",
  "mchNo": "10093518558",
  "sign": "由公共客户端计算"
}

业务错误与处理

调用失败时查看 msg 提示；业务结果以返回状态或后续结果查询为准。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792740000",
  "data": {}
}

以下示例说明响应结构；请结合 code 和业务状态判断处理结果。

业务响应字段

字段类型必填说明
data按渠道返回—业务处理结果，具体字段须在接入前确认。
/api/open.merchant/prePay 聚合支付下单

POSTContent-Type application/json公共协议 ↗

为已开通收款能力的商户创建支付订单。按支付方式获取二维码内容、H5 支付链接或支付调起参数，完成支付后通过结果通知或订单查询确认支付状态。

应用与收款商户须已开通所选支付方式及场景的产品。channel 固定填写 yibao；下表中的微信或支付宝选择使用 payChannel 参数。

code=1 表示下单成功，不表示付款完成。请以已验签的支付结果通知或 orderQuery 查询结果确认支付状态。

每笔业务使用唯一 orderId。请求超时或结果不确定时，先查询原订单；同单重试保持业务参数一致。

通知成功应答为 HTTP 2xx 与纯文本 SUCCESS；同一通知最多自动投递 10 次（含首次），失败等待间隔为 10、20、40、80、160、320、640、1280、2560 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。

业务参数

参数类型必填 / 位置说明
channelstring是收款通道标识，当前固定填写 yibao。 取值：yibao。
merchantNostring是收款商户号，可从商户进件结果获取；须已开通对应支付能力。
orderAmountstring是订单金额，单位元，范围 0.01 至 99999999.99，最多两位小数。
payWaystring是支付方式须与 payChannel 组合选择：WECHAT 支持 USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY；ALIPAY 支持 USER_SCAN / MINI_PROGRAM / ALIPAY_LIFE / H5_PAY。 取值：USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY / ALIPAY_LIFE / H5_PAY。
goodsNamestring是商品名称，必填。 最大 85 个字符。
userIdstring公众号 / 小程序 / 生活号必填付款人标识：微信公众号或小程序填写 openId，支付宝生活号或小程序填写支付宝 userId，须与 appId 对应。扫码、微信 SDK 和 H5 支付可不传。 最大 128 个字符。
appIdstring公众号 / 小程序 / 生活号 / SDK 必填支付应用 ID；公众号、小程序、生活号和微信 SDK 支付必传，须对应已开通的支付应用。与公共参数 app_id 区分填写。 最大 64 个字符。
orderIdstring否商户业务订单号，建议必传且全局唯一。由 1 至 64 位字母、数字、下划线或连字符组成；不传则自动生成。相同订单重试须保持业务参数一致。 最大 64 个字符。
scenestring否支付场景：ONLINE 线上，OFFLINE 线下。微信支持两种场景，支付宝仅支持 OFFLINE；须已开通对应场景的支付产品。 取值：ONLINE / OFFLINE。 默认："OFFLINE"。
userIpstring否付款人 IP 地址，可不传。
payChannelstring否支付渠道：WECHAT 微信，ALIPAY 支付宝。建议显式填写；省略时 ALIPAY_LIFE、H5_PAY 默认 ALIPAY，其余默认 WECHAT。小程序支付请按实际渠道填写。与固定为 yibao 的 channel 区分。 取值：WECHAT / ALIPAY。
expiredTimestring否支付截止时间，使用北京时间 yyyy-MM-dd HH:mm:ss，须晚于当前时间。省略时默认 30 分钟有效；同单重试保持原值。
fundProcessTypestring否资金处理方式。REAL_TIME：支付成功后自动处理费用并释放商户余款。DELAY_SETTLE：保留商户余款待后续处理；后续可按订单分账接口处理，完结分账暂未开放。 取值：REAL_TIME / DELAY_SETTLE。 默认："REAL_TIME"。
notifyUrlstring否支付成功通知地址，建议填写可从公网访问的 HTTP(S) 地址，使用标准端口，不能包含用户名或 URL 片段。不传则不发送支付通知。 最大 2048 个字符。
memostring否业务备注，在支付通知和订单查询中原样返回。 最大 256 个字符。
businessInfostring否业务扩展信息，填写 JSON 对象或数组字符串，最多 4096 个 UTF-8 字节；在支付通知和订单查询中原样返回。 最大 4096 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

支付渠道、场景与方式组合

payChannelscenepayWay
WECHATONLINE / OFFLINEUSER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY
ALIPAYOFFLINEUSER_SCAN / MINI_PROGRAM / ALIPAY_LIFE / H5_PAY

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/prePay
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "orderId": "SH20261023000001",
  "orderAmount": "100.00",
  "payChannel": "WECHAT",
  "payWay": "USER_SCAN",
  "goodsName": "测试商品",
  "notifyUrl": "https://merchant.example.com/payment/notify",
  "memo": "外部订单备注",
  "businessInfo": "{\"externalOrderId\":\"EXT202610230001\"}",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
payChannel 与 payWay 组合不支持200按文档支持的微信/支付宝组合提交。
订单金额须为 0.01 至 99999999.99 元，最多两位小数200用十进制元金额提交，勿传超精度或科学计数法字符串。
goodsName 必须为非空字符串且不超过 85 个字符200明确提供商品名称。
orderId 已存在且请求归属或业务参数不一致200勿跨应用复用订单号或修改同一订单业务参数。
expiredTime 必须晚于当前时间200按北京时间设置未来截止时间。
应用未启用该支付产品200联系平台确认当前应用已开通所选支付产品。
scene 仅支持 ONLINE、OFFLINE200按支持的场景取值提交；省略时默认 OFFLINE。
支付宝支付当前仅支持 scene=OFFLINE200payChannel=ALIPAY 时使用 OFFLINE。
公众号、小程序、生活号支付必须明确提供 appId 和 userId200按所选支付方式提交非空的支付应用 ID 和付款人标识。
微信 SDK 支付必须明确提供 appId200SDK_PAY 必须填写支付应用 appId；userId 可省略。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "success",
  "time": "1792740000",
  "data": {
    "response_arr": "https://qr.yeepay.com/******",
    "pay_way": "USER_SCAN",
    "channel": "WECHAT",
    "order_id": "202610221530001234",
    "unique_order_no": "1001202610220000001"
  }
}

业务响应字段

字段类型必填说明
data.response_arrstring / object是USER_SCAN 返回二维码内容字符串；H5_PAY 返回支付跳转链接字符串；公众号、小程序、生活号和微信 SDK 返回支付调起参数，可能为对象或 JSON 字符串，请按所选支付方式解析。
data.pay_waystring是请求的支付方式。
data.channelstring是支付渠道：WECHAT 微信，ALIPAY 支付宝。
data.order_idstring是订单号，用于查询和核对支付结果。
data.unique_order_nostring是支付流水号，尚未取得时为空字符串。

支付成功通知

支付成功后，下单时填写的 notifyUrl 将收到 POST JSON 通知。通知签名方式与下单请求一致；HMAC-SHA256 使用应用密钥验签，RSA2 使用平台提供的通知公钥验签。重复通知使用同一 notify_id，请在业务处理成功后返回 SUCCESS。

通知字段

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
notify_idstring是固定通知标识，重试时不变；请使用此字段去重，避免重复处理业务。
orderIdstring是订单号，对应下单时的 orderId；下单未传时为返回的生成值。
merchantNostring是收款商户号。
orderAmountstring是原订单金额，单位元，两位小数；须与接入方订单核对。
statusstring是SUCCESS 表示该订单支付成功；请核对订单号与金额后处理业务。 取值：SUCCESS。
uniqueOrderNostring是支付流水号，可用于核对交易。
paidTimestring是支付成功时间，北京时间 yyyy-MM-dd HH:mm:ss。
payChannelstring是本次支付渠道：WECHAT 微信，ALIPAY 支付宝。 取值：WECHAT / ALIPAY。
payWaystring是本次订单的支付方式，与下单请求一致。 取值：USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY / ALIPAY_LIFE / H5_PAY。
fundProcessTypestring是下单时选择的资金处理方式。 取值：REAL_TIME / DELAY_SETTLE。 默认："REAL_TIME"。
memostring是下单时提交的业务备注原值。 最大 256 个字符。
businessInfostring是下单时提交的 businessInfo 原始 JSON 字符串。 最大 4096 个字符。

通知结构示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "本次通知生成的随机串",
  "notify_id": "N_example_stable_notification_id",
  "orderId": "SH20261023000001",
  "merchantNo": "10000000002",
  "orderAmount": "100.00",
  "status": "SUCCESS",
  "uniqueOrderNo": "1001202610230000001",
  "paidTime": "2026-10-23 17:00:00",
  "payChannel": "WECHAT",
  "payWay": "USER_SCAN",
  "fundProcessType": "REAL_TIME",
  "memo": "外部订单备注",
  "businessInfo": "{\"externalOrderId\":\"EXT202610230001\"}",
  "sign": "平台使用应用凭证生成的通知签名"
}

请先验签，核对业务请求及金额，使用 notify_id 去重；通知包含 version 时，较低版本不得覆盖新状态，包含 detailId 时须分别比较每笔明细的版本。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS（大小写均可）。通知失败会重试，请避免重复发货或记账。

$payload = json_decode(file_get_contents('php://input'), true);
// HMAC 使用 app_secret；RSA2 第三个参数传平台提供的通知公钥。
$verified = is_array($payload) && $client->verifyNotification($payload, $platformPublicKey ?? '');
// 验签通过后，核对业务请求及金额，完成业务处理和通知去重，再应答 SUCCESS。

异步通知完整指南 ↗ · 成功确认与停止规则 ↗ · 最多 10 次投递及失败间隔 ↗

/api/open.merchant/balanceDivide 余额分账申请

POSTContent-Type application/json公共协议 ↗

使用当前应用商户的资金账户，向同一应用下的商户账户申请分账。手续费承担方式可逐笔选择。

出款商户与全部接收商户均须属于当前应用，且已满足相应分账产品和商户关系要求。接口权限标识为 open.merchant/balancedivide。

仅支持资金账户向商户账户分账。明细中的 ledgerType 填写 MERCHANT；不可提交 parentMerchantNo、bankAccountBookNo、fundType 等未列出的字段。

每笔明细可填写 feeChargeSide=OUTSIDE 或 INSIDE；省略时为 OUTSIDE。实际扣账、到账和手续费金额以结果为准，不能只按申请金额推算。

code=1、status=ACCEPTED 仅表示申请受理。请通过签名通知或 balanceDivideQuery 确认每笔处理结果。

同一出款商户内的 divideRequestId 须唯一。同一应用、相同请求号和相同业务参数重复调用时返回原受理信息，修改参数时拒绝。

请求超时、受理结果不明确或暂未查到记录时，继续使用原 divideRequestId 查询，不能换号重复申请。

通知逐笔发送，请使用 notify_id 去重，并按 detailId 分别记录最新 version。不同明细的版本相互独立，较低版本不得覆盖同一明细的新状态。

成功后仍可能因冲退收到更高版本的 FAIL 通知，请按更新版本处理；reversed=true 表示已确认该明细曾成功、之后转为失败。

notifyUrl 选填；省略或为空字符串时不发送通知，仍可使用 balanceDivideQuery 查询结果。

通知成功应答为 HTTP 2xx 与纯文本 SUCCESS；同一通知最多自动投递 10 次（含首次），失败等待间隔为 10、20、40、80、160、320、640、1280、2560 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。

业务参数

参数类型必填 / 位置说明
channelstring是收款通道标识，固定填写 yibao。 取值：yibao。
merchantNostring是出款商户号，须属于当前签名应用且已完成入网并开通分账能力。 最大 16 个字符。
divideRequestIdstring是你方生成的业务请求号，同一出款商户内唯一。结果不明确时保持原号查询，不能换号重试。 最大 64 个字符。
divideDetailstring是JSON 数组字符串，原文及规范编码后均不超过 1024 个 UTF-8 字节，包含 1 至 30 笔明细；各笔字段见下表。 最大 1024 个字符。
notifyUrlstring否接收逐笔分账结果通知的公网 HTTP(S) 地址。省略或为空字符串时不发送通知，请使用 balanceDivideQuery 查询。 最大 2048 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

divideDetail JSON 明细字段

该参数仍按 JSON 字符串提交，下表说明字符串中每笔明细的字段。

参数类型必填 / 位置说明
divideDetail[].ledgerNostring是接收商户号，须为当前应用下已完成入网的商户。 最大 16 个字符。
divideDetail[].ledgerTypestring是接收方类型，目前仅支持商户账户。 取值：MERCHANT。
divideDetail[].divideAmountstring是分账金额，单位元；使用大于零、最多两位小数的十进制字符串。
divideDetail[].feeChargeSidestring否手续费承担方式。OUTSIDE：出款方额外承担；INSIDE：从接收方到账金额中扣除。是否适用取决于商户已开通的计费方式，实际费用及扣账、到账金额以结果为准。 取值：OUTSIDE / INSIDE。 默认："OUTSIDE"。
divideDetail[].remarkstring否分账附言，最多 32 字，不得包含换行或控制字符。 最大 32 个字符。
divideDetail[].divideReasonstring否分账说明，最多 40 字，不得包含换行或控制字符。 最大 40 个字符。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/balanceDivide
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "divideRequestId": "DIV_20261024_0001",
  "divideDetail": "[{\"ledgerNo\":\"10000000003\",\"ledgerType\":\"MERCHANT\",\"divideAmount\":\"100.00\",\"feeChargeSide\":\"OUTSIDE\",\"remark\":\"订单结算\",\"divideReason\":\"业务分账\"}]",
  "notifyUrl": "https://your-domain.com/notify/balance-divide",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
余额分账暂未开放200请确认应用和商户已获得余额分账接入权限。
商户不存在或无权访问200核对出款商户及每一笔接收商户，均须属于当前应用。
divideDetail 必须为不超过 1024 字节的有效 JSON 数组字符串200使用 JSON 数组字符串，不要传对象、直接数组或 HTML 转义后的字符串。
分账明细编码后不得超过 1024 字节200减少单次明细数量或附言长度；每次最多 30 笔，同时满足长度限制。
分账接收方不可重复200同一次申请中每个接收商户仅可出现一次。
feeChargeSide 仅支持 OUTSIDE、INSIDE200在每笔明细内填写有效的承担方式。
divideRequestId 已存在且归属或业务参数不一致200查询并核对原申请，勿修改参数或换应用重提。
分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试200原申请可能已受理，继续使用原请求号核对结果。
余额分账不支持参数 <字段>200按参数表提交请求，删除未开放字段；结果通知地址使用 notifyUrl。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "分账申请已受理，请查询最终结果",
  "time": "1792840000",
  "data": {
    "merchantNo": "10000000002",
    "divideRequestId": "DIV_20261024_0001",
    "status": "ACCEPTED",
    "acceptedAt": 1792840000,
    "totalAmount": "100.00",
    "detailCount": 1,
    "detailList": [
      {
        "detailId": "DD_example_detail",
        "ledgerNo": "10000000003",
        "ledgerType": "MERCHANT",
        "divideAmount": "100.00",
        "feeChargeSide": "OUTSIDE"
      }
    ]
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是出款商户号。
data.divideRequestIdstring是原分账请求号。
data.statusstring是ACCEPTED 仅表示受理，不代表各笔资金处理完成。 取值：ACCEPTED。
data.acceptedAtinteger是受理确认的 Unix 秒时间戳。
data.totalAmountstring是申请分账总金额，不含可能额外承担的手续费。
data.detailCountinteger是申请明细数量。
data.detailListarray是
data.detailList[].detailIdstring是稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。 最大 64 个字符。
data.detailList[].ledgerNostring是接收商户号。 最大 16 个字符。
data.detailList[].ledgerTypestring是接收方类型。 取值：MERCHANT。
data.detailList[].divideAmountstring是申请分账金额，单位元。
data.detailList[].feeChargeSidestring是本笔申请的手续费承担方式。 取值：OUTSIDE / INSIDE。

逐笔余额分账结果通知

通知采用 POST application/json，签名方式与申请一致。HMAC-SHA256 使用应用密钥验签；RSA2 使用通知公钥验签。核对商户、请求号、明细和金额，按 notify_id 去重、按 detailId 分别比较 version。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试，同一版本的业务内容不变。

通知字段

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
detailIdstring是稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。 最大 64 个字符。
detailNostring / null是分账处理明细号，尚未取得时为 null。 最大 64 个字符。
ledgerNostring是接收商户号。 最大 16 个字符。
ledgerTypestring是接收方类型。 取值：MERCHANT。
divideAmountstring是申请分账金额，单位元。
feeChargeSidestring是本笔申请的手续费承担方式。 取值：OUTSIDE / INSIDE。
statusstring是单笔处理状态；成功后发生冲退时仍可能变为 FAIL。 取值：SUCCESS / FAIL。
reversedboolean是是否已确认本笔分账曾成功、之后转为失败。
versioninteger是同一 detailId 内递增的通知版本，从 1 开始；不同明细分别比较，较低版本不得覆盖新状态。
receiveAmountstring / null是实际到账金额；尚未确认时为 null，不得按申请金额或零推算。
debitAmountstring / null是实际扣账金额；尚未确认时为 null。
feeAmountstring / null是实际分账手续费；尚未确认时为 null。
finishTimestring / null是结果中返回的完成时间；尚未取得时为 null。
failReasonstring是失败原因，无失败原因时为空字符串。
remarkstring是申请时填写的附言。
divideReasonstring是申请时填写的分账说明。
notify_idstring是固定通知标识，重试不变。
eventTypestring是通知类型。 取值：BALANCE_DIVIDE_RESULT。
merchantNostring是原出款商户号。
divideRequestIdstring是原分账请求号。
occurredAtinteger是本版本结果的确认时间，Unix 秒时间戳；重试时不变。

通知结构示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792840060",
  "nonce": "本次通知生成的新随机串",
  "sign": "通知签名",
  "notify_id": "BN_example_notification",
  "eventType": "BALANCE_DIVIDE_RESULT",
  "merchantNo": "10000000002",
  "divideRequestId": "DIV_20261024_0001",
  "detailId": "DD_example_detail",
  "detailNo": "DETAIL_EXAMPLE_1",
  "ledgerNo": "10000000003",
  "ledgerType": "MERCHANT",
  "divideAmount": "100.00",
  "feeChargeSide": "OUTSIDE",
  "status": "SUCCESS",
  "reversed": false,
  "version": 1,
  "receiveAmount": "100.00",
  "debitAmount": "100.02",
  "feeAmount": "0.02",
  "finishTime": "2026-10-24 20:00:00",
  "failReason": "",
  "remark": "订单结算",
  "divideReason": "业务分账",
  "occurredAt": 1792840060
}

请先验签，核对业务请求及金额，使用 notify_id 去重；通知包含 version 时，较低版本不得覆盖新状态，包含 detailId 时须分别比较每笔明细的版本。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS（大小写均可）。通知失败会重试，请避免重复发货或记账。

$payload = json_decode(file_get_contents('php://input'), true);
// HMAC 使用 app_secret；RSA2 第三个参数传平台提供的通知公钥。
$verified = is_array($payload) && $client->verifyNotification($payload, $platformPublicKey ?? '');
// 验签通过后，核对业务请求及金额，完成业务处理和通知去重，再应答 SUCCESS。

异步通知完整指南 ↗ · 成功确认与停止规则 ↗ · 最多 10 次投递及失败间隔 ↗

/api/open.merchant/balanceDivideQuery 余额分账结果查询

POSTContent-Type application/json公共协议 ↗

按原出款商户号和分账请求号，查询本应用申请的逐笔余额分账结果、实际金额和手续费。

仅可查询本应用发起的申请；查询权限标识为 open.merchant/balancedividequery，申请权限与查询权限分别授权。

使用原 merchantNo 和 divideRequestId 查询；不能用支付订单号、结算请求号替代。

请完整处理 detailList。不同明细可有不同结果；PROCESSING 表示尚有明细待确认，PARTIAL_SUCCESS 表示全部处理后部分成功。

成功结果后续仍可能变为 FAIL，请结合较高版本通知及查询结果处理冲退。

所有金额以元为单位，返回两位小数字符串。null 表示未取得有效金额，不得按零或申请金额处理；任一明细金额未知时，对应汇总金额为 null。

queriedAt 是最后一次成功核对结果的 Unix 秒时间戳。查询结果可能短暂延迟，建议轮询间隔不短于 5 秒。

查询失败、受理结果不明或暂未查到申请，均不能作为换号重新分账的依据。

商户关联至其他应用后，历史申请仍仅限原发起应用查询。

业务参数

参数类型必填 / 位置说明
channelstring是收款通道标识，固定填写 yibao。 取值：yibao。
merchantNostring是出款商户号，须属于当前签名应用且已完成入网并开通分账能力。 最大 16 个字符。
divideRequestIdstring是你方生成的业务请求号，同一出款商户内唯一。结果不明确时保持原号查询，不能换号重试。 最大 64 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/balanceDivideQuery
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "divideRequestId": "DIV_20261024_0001",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
分账申请不存在或无权访问200核对原商户号、分账请求号及发起应用。
余额分账查询暂不可用，请稍后使用原请求号查询或联系技术支持200继续用原请求号核对，勿换号再次申请。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "查询成功",
  "time": "1792840000",
  "data": {
    "merchantNo": "10000000002",
    "divideRequestId": "DIV_20261024_0001",
    "status": "SUCCESS",
    "totalAmount": "100.00",
    "detailCount": 1,
    "successCount": 1,
    "failCount": 0,
    "processingCount": 0,
    "acceptedAt": 1792840000,
    "queriedAt": 1792840060,
    "detailList": [
      {
        "detailId": "DD_example_detail",
        "detailNo": "DETAIL_EXAMPLE_1",
        "ledgerNo": "10000000003",
        "ledgerType": "MERCHANT",
        "divideAmount": "100.00",
        "feeChargeSide": "OUTSIDE",
        "status": "SUCCESS",
        "reversed": false,
        "version": 1,
        "receiveAmount": "100.00",
        "debitAmount": "100.02",
        "feeAmount": "0.02",
        "finishTime": "2026-10-24 20:00:00",
        "failReason": "",
        "remark": "订单结算",
        "divideReason": "业务分账"
      }
    ],
    "receiveAmount": "100.00",
    "debitAmount": "100.02",
    "feeAmount": "0.02"
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是出款商户号。
data.divideRequestIdstring是原分账请求号。
data.statusstring是汇总状态。UNKNOWN：受理结果未确认；REJECTED：申请未受理；PROCESSING：仍有明细待确认；SUCCESS：当前全部成功；PARTIAL_SUCCESS：全部处理后部分成功；FAIL：当前全部失败。成功结果后续仍可能发生变化，须处理更新的结果通知。 取值：UNKNOWN / REJECTED / PROCESSING / SUCCESS / PARTIAL_SUCCESS / FAIL。
data.totalAmountstring是申请分账总金额，不含可能额外承担的手续费。
data.detailCountinteger是
data.successCountinteger是
data.failCountinteger是
data.processingCountinteger是
data.acceptedAtinteger是受理确认时间，Unix 秒时间戳；未确认时为 0。
data.queriedAtinteger是最后一次成功核对分账结果的 Unix 秒时间戳；尚未取得有效查询结果时为 0。
data.detailListarray是
data.detailList[].detailIdstring是稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。 最大 64 个字符。
data.detailList[].detailNostring / null是分账处理明细号，尚未取得时为 null。 最大 64 个字符。
data.detailList[].ledgerNostring是接收商户号。 最大 16 个字符。
data.detailList[].ledgerTypestring是接收方类型。 取值：MERCHANT。
data.detailList[].divideAmountstring是申请分账金额，单位元。
data.detailList[].feeChargeSidestring是本笔申请的手续费承担方式。 取值：OUTSIDE / INSIDE。
data.detailList[].statusstring是单笔处理状态；成功后发生冲退时仍可能变为 FAIL。 取值：PROCESSING / SUCCESS / FAIL。
data.detailList[].reversedboolean是是否已确认本笔分账曾成功、之后转为失败。
data.detailList[].versioninteger是本明细的通知版本，尚无结果通知时为 0；不同明细分别计数。
data.detailList[].receiveAmountstring / null是实际到账金额；尚未确认时为 null，不得按申请金额或零推算。
data.detailList[].debitAmountstring / null是实际扣账金额；尚未确认时为 null。
data.detailList[].feeAmountstring / null是实际分账手续费；尚未确认时为 null。
data.detailList[].finishTimestring / null是结果中返回的完成时间；尚未取得时为 null。
data.detailList[].failReasonstring是失败原因，无失败原因时为空字符串。
data.detailList[].remarkstring是申请时填写的附言。
data.detailList[].divideReasonstring是申请时填写的分账说明。
data.receiveAmountstring / null是已确认的逐笔到账金额合计；任一明细金额未知时为 null。
data.debitAmountstring / null是已确认的逐笔扣账金额合计；任一明细金额未知时为 null。
data.feeAmountstring / null是已确认的逐笔手续费合计；任一明细金额未知时为 null。
/api/open.merchant/orderDivide 订单分账申请

POSTContent-Type application/json公共协议 ↗

将原订单的可分账金额，按指定金额分配至同一应用下的商户。

仅支持已支付且当前可分账的 DELAY_SETTLE 订单。请先查询 orderQuery 的 canDivide 和 availableDivideAmount；实际是否可提交，以本次申请校验为准。

仅按金额分账，单次 1 至 5 笔明细，JSON 字符串原文及规范编码后均不超过 1000 个 UTF-8 字节。接收商户不得重复。

本接口使用订单剩余可分账金额，与资金账户余额不同。未分配余款继续保留，暂不开放解冻余款或指定比例分账。

同一商户内 divideRequestId 唯一。同一应用使用相同请求号、订单及规范化业务参数重复调用时返回原受理信息；更改参数时拒绝。

同一订单上一笔分账结果未确认前，不能发起下一笔。超时、处理中、未知结果或暂未查到时，只查询原 divideRequestId，不能换号重复申请。

一次申请按整批处理，任一接收方失败则整批失败，没有部分成功状态。SUCCESS 不等于已提现至银行卡。

notifyUrl 为唯一的结果通知地址，选填；省略或为空时不发送通知，请通过 orderDivideQuery 查询。通知验签后按 notify_id 去重，并按同一订单及请求号的 version 处理更新。

通知成功应答为 HTTP 2xx 与纯文本 SUCCESS；同一通知最多自动投递 10 次（含首次），失败等待间隔为 10、20、40、80、160、320、640、1280、2560 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，固定填写 yibao。 取值：yibao。
merchantNostring是原订单的收款商户编号，须属于当前应用。 最大 11 个字符。
orderIdstring是原支付订单号，须为当前应用创建的订单。 最大 64 个字符。
divideRequestIdstring是你方生成的分账请求号，同一收款商户内唯一。 最大 64 个字符。
divideDetailstring是按金额分账的 JSON 数组字符串，长度限制为 1000 个 UTF-8 字节；各笔字段见下表。 最大 1000 个字符。
notifyUrlstring否接收本批订单分账结果签名通知的公网 HTTP(S) 地址。选填；省略或为空字符串时不发送通知。 最大 2048 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

divideDetail JSON 明细字段

该参数仍按 JSON 字符串提交，下表说明字符串中每笔明细的字段。

参数类型必填 / 位置说明
divideDetail[].ledgerNostring是接收商户编号，须属于同一应用且已完成入网及分账关系配置。 最大 11 个字符。
divideDetail[].amountstring是本笔分账金额，单位元，大于零，最多两位小数；请按字符串填写。
divideDetail[].ledgerTypestring否商户间分账，省略时使用 MERCHANT2MERCHANT。 取值：MERCHANT2MERCHANT。 默认："MERCHANT2MERCHANT"。
divideDetail[].divideDetailDescstring否分账说明，单行文本，最多 128 个 UTF-8 字节。 最大 128 个字符。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/orderDivide
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "orderId": "ORDER_20261025_0001",
  "divideRequestId": "DIVIDE_20261025_0001",
  "divideDetail": "[{\"ledgerNo\":\"10000000003\",\"amount\":\"10.37\",\"divideDetailDesc\":\"供应商结算\"}]",
  "notifyUrl": "https://your-domain.com/notify/order-divide",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
订单暂不可分账，请稍后查询200先查询原订单的 canDivide，确认业务条件后再提交。
该订单存在未确认的分账申请，请先查询原申请200使用上一笔 divideRequestId 查询，不能更换请求号重复申请。
分账总金额超过订单可用额度 / 分账总金额超过订单剩余可分账金额200核对 availableDivideAmount，减少本次申请金额。
分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试200继续查询原申请；未查到不能认定原申请未受理。
订单分账不支持参数 <字段>200按参数表提交，删除比例、发起方、解冻余款及其他未开放字段。
商户不存在或无权访问200核对订单、出款商户及全部接收商户的应用归属。
divideRequestId 已存在且归属或业务参数不一致200核对原申请，不能更改订单、金额、接收方、通知地址或应用重复提交。
请稍后发起订单分账，勿频繁调用200支付成功后稍等，且同一订单分账申请至少间隔 3 秒。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792922400",
  "data": {
    "orderId": "ORDER_20261025_0001",
    "merchantNo": "10000000002",
    "divideRequestId": "DIVIDE_20261025_0001",
    "status": "ACCEPTED",
    "totalAmount": "10.37",
    "detailCount": 1,
    "acceptedAt": 1792922400
  }
}

业务响应字段

字段类型必填说明
data.orderIdstring是原支付订单号。
data.merchantNostring是收款商户编号。
data.divideRequestIdstring是你方分账请求号。
data.statusstring是ACCEPTED 表示申请已受理，请继续查询最终结果。 取值：ACCEPTED。
data.totalAmountstring是申请分账总金额，单位元。
data.detailCountinteger是本次申请的明细笔数。
data.acceptedAtinteger是申请受理时间，Unix 秒。

订单分账结果通知

每次申请按整批发送最终结果。通知签名方式与原申请一致：HMAC-SHA256 使用应用密钥验签，RSA2 使用通知公钥验签。收到较低版本或重复通知时，不重复记账。

通知字段

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
orderIdstring是原支付订单号。
merchantNostring是收款商户编号。
divideRequestIdstring是你方分账请求号。
statusstring是本批分账最终状态。 取值：SUCCESS / FAIL。
totalAmountstring是申请分账总金额，单位元。
detailCountinteger是本次申请的明细笔数。
acceptedAtinteger是申请受理时间，Unix 秒。
versioninteger是结果版本，按同一 orderId、divideRequestId 比较。
feeAmountstring / null是本批实际分账手续费合计；任何明细未确认时为 null。
receiveAmountstring / null是本批实际入账金额合计；任何明细未确认时为 null。
finishTimestring / null是分账完成时间；尚未取得为 null。
detailListarray是本批分账全部明细，每项包含接收商户、申请金额、实际手续费及实际入账金额。
detailList[].detailIdstring是分账明细标识。
detailList[].detailNostring / null是分账成功后的明细流水号；尚未取得为 null。
detailList[].ledgerNostring是接收商户编号。
detailList[].ledgerTypestring是商户间分账。 取值：MERCHANT2MERCHANT。
detailList[].amountstring是申请金额，单位元。
detailList[].feeAmountstring / null是实际分账手续费，单位元；null 表示尚未确认。
detailList[].receiveAmountstring / null是实际入账金额，单位元；null 表示尚未确认。
detailList[].divideDetailDescstring是本笔分账说明。
notify_idstring是通知唯一标识，重复通知保持不变。
eventTypestring是通知类型。 取值：ORDER_DIVIDE_RESULT。

通知结构示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "orderId": "ORDER_20261025_0001",
  "merchantNo": "10000000002",
  "divideRequestId": "DIVIDE_20261025_0001",
  "status": "SUCCESS",
  "totalAmount": "10.37",
  "detailCount": 1,
  "acceptedAt": 1792922400,
  "version": 1,
  "feeAmount": "0.02",
  "receiveAmount": "10.37",
  "finishTime": "2026-10-25 18:00:00",
  "detailList": [
    {
      "detailId": "OIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "detailNo": "DIVIDE_DETAIL_EXAMPLE",
      "ledgerNo": "10000000003",
      "ledgerType": "MERCHANT2MERCHANT",
      "amount": "10.37",
      "feeAmount": "0.02",
      "receiveAmount": "10.37",
      "divideDetailDesc": "供应商结算"
    }
  ],
  "notify_id": "ONbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "eventType": "ORDER_DIVIDE_RESULT",
  "sign": "由实际通知参数计算"
}

请先验签，核对业务请求及金额，使用 notify_id 去重；通知包含 version 时，较低版本不得覆盖新状态，包含 detailId 时须分别比较每笔明细的版本。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS（大小写均可）。通知失败会重试，请避免重复发货或记账。

$payload = json_decode(file_get_contents('php://input'), true);
// HMAC 使用 app_secret；RSA2 第三个参数传平台提供的通知公钥。
$verified = is_array($payload) && $client->verifyNotification($payload, $platformPublicKey ?? '');
// 验签通过后，核对业务请求及金额，完成业务处理和通知去重，再应答 SUCCESS。

异步通知完整指南 ↗ · 成功确认与停止规则 ↗ · 最多 10 次投递及失败间隔 ↗

/api/open.merchant/orderDivideQuery 订单分账结果查询

POSTContent-Type application/json公共协议 ↗

按原订单号及分账请求号查询整批处理结果、明细和实际分账费用。

只可查询原发起应用的分账申请；商户后续改绑不转移历史记录归属。

查询原申请不会再次发起分账。结果为 UNKNOWN 或 PROCESSING 时继续查询；请勿换请求号重复申请。

feeAmount、receiveAmount 为已确认的实际金额，null 表示未知，不能按零费用或申请金额推算。

接口权限标识为 open.merchant/orderdividequery；申请权限为 open.merchant/orderdivide。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，固定填写 yibao。 取值：yibao。
merchantNostring是原订单的收款商户编号，须属于当前应用。 最大 11 个字符。
orderIdstring是原支付订单号，须为当前应用创建的订单。 最大 64 个字符。
divideRequestIdstring是你方生成的分账请求号，同一收款商户内唯一。 最大 64 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/orderDivideQuery
Content-Type: application/json

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "orderId": "ORDER_20261025_0001",
  "divideRequestId": "DIVIDE_20261025_0001",
  "sign": "由公共客户端计算"
}

业务错误与处理

msg / 情况HTTP处理说明
订单暂不可分账，请稍后查询200先查询原订单的 canDivide，确认业务条件后再提交。
该订单存在未确认的分账申请，请先查询原申请200使用上一笔 divideRequestId 查询，不能更换请求号重复申请。
分账总金额超过订单可用额度 / 分账总金额超过订单剩余可分账金额200核对 availableDivideAmount，减少本次申请金额。
分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试200继续查询原申请；未查到不能认定原申请未受理。
订单分账不支持参数 <字段>200按参数表提交，删除比例、发起方、解冻余款及其他未开放字段。
商户不存在或无权访问200核对订单、出款商户及全部接收商户的应用归属。
divideRequestId 已存在且归属或业务参数不一致200核对原申请，不能更改订单、金额、接收方、通知地址或应用重复提交。
请稍后发起订单分账，勿频繁调用200支付成功后稍等，且同一订单分账申请至少间隔 3 秒。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "操作成功",
  "time": "1792922400",
  "data": {
    "orderId": "ORDER_20261025_0001",
    "merchantNo": "10000000002",
    "divideRequestId": "DIVIDE_20261025_0001",
    "status": "SUCCESS",
    "totalAmount": "10.37",
    "detailCount": 1,
    "acceptedAt": 1792922400,
    "version": 1,
    "feeAmount": "0.02",
    "receiveAmount": "10.37",
    "finishTime": "2026-10-25 18:00:00",
    "queriedAt": 1792922405,
    "detailList": [
      {
        "detailId": "OIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "detailNo": "DIVIDE_DETAIL_EXAMPLE",
        "ledgerNo": "10000000003",
        "ledgerType": "MERCHANT2MERCHANT",
        "amount": "10.37",
        "feeAmount": "0.02",
        "receiveAmount": "10.37",
        "divideDetailDesc": "供应商结算"
      }
    ]
  }
}

业务响应字段

字段类型必填说明
data.orderIdstring是原支付订单号。
data.merchantNostring是收款商户编号。
data.divideRequestIdstring是你方分账请求号。
data.statusstring是UNKNOWN 结果未确认；PROCESSING 处理中；SUCCESS 整批成功；FAIL 整批失败；REJECTED 明确未受理。 取值：UNKNOWN / PROCESSING / SUCCESS / FAIL / REJECTED。
data.totalAmountstring是申请分账总金额，单位元。
data.detailCountinteger是本次申请的明细笔数。
data.acceptedAtinteger是申请受理时间，Unix 秒。
data.versioninteger是结果版本，按同一 orderId、divideRequestId 比较。
data.feeAmountstring / null是本批实际分账手续费合计；任何明细未确认时为 null。
data.receiveAmountstring / null是本批实际入账金额合计；任何明细未确认时为 null。
data.finishTimestring / null是分账完成时间；尚未取得为 null。
data.queriedAtinteger是最近有效结果查询时间，Unix 秒；尚无有效查询为 0。
data.detailListarray是
data.detailList[].detailIdstring是分账明细标识。
data.detailList[].detailNostring / null是分账成功后的明细流水号；尚未取得为 null。
data.detailList[].ledgerNostring是接收商户编号。
data.detailList[].ledgerTypestring是商户间分账。 取值：MERCHANT2MERCHANT。
data.detailList[].amountstring是申请金额，单位元。
data.detailList[].feeAmountstring / null是实际分账手续费，单位元；null 表示尚未确认。
data.detailList[].receiveAmountstring / null是实际入账金额，单位元；null 表示尚未确认。
data.detailList[].divideDetailDescstring是本笔分账说明。
/api/open.merchant/orderQuery 开放订单查询

POSTContent-Type application/json公共协议 ↗

查询当前应用发起的订单，返回订单金额、支付状态、费用与资金处理状态，以及剩余可分账金额。仅能查询当前应用的订单；金额为查询时点的快照，具体可用情况以 unSplitAmount 和 unSplitAmountQueriedAt 为准。

使用下单返回的 order_id 或请求时提交的 orderId 查询；请求仍需携带公共参数并重新签名。

unSplitAmount 为剩余可分账金额，单位元，以两位小数字符串返回。null 表示尚未取得有效金额，不可按零处理；0.00 表示确认剩余金额为零。

unSplitAmountQueriedAt 是金额查询的 Unix 秒时间戳，未取得金额时为 0。建议轮询间隔不短于 5 秒。

订单支付状态可能更新延迟。请结合已验签的支付结果通知确认；查询接口仅返回订单信息。

订单总手续费查看 totalFee；unSplitAmount 不能直接按订单金额减总手续费推算，也不是商户账户余额。保留资金后续处理能力请先确认适用范围。

业务参数

参数类型必填 / 位置说明
orderIdstring是订单号；只能查询当前应用通过 prePay 创建的订单。 最大 64 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/orderQuery
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792713600",
  "nonce": "example-query-nonce",
  "sign": "请在服务端生成签名",
  "orderId": "OPEN_ORDER_20261023_001"
}

业务错误与处理

msg / 情况HTTP处理说明
订单不存在或无权访问200核对订单号和调用应用；仅支持查询本应用通过 prePay 创建的订单。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "success",
  "time": "1792713600",
  "data": {
    "orderId": "OPEN_ORDER_20261023_001",
    "merchantNo": "10000000002",
    "uniqueOrderNo": "YOP_ORDER_20261023_001",
    "orderAmount": "100.00",
    "status": 1,
    "payChannel": "WECHAT",
    "payWay": "USER_SCAN",
    "platformFee": "0.38",
    "fundProcessType": "DELAY_SETTLE",
    "fundStatus": "RESERVED",
    "notifyStatus": "SUCCESS",
    "paidAt": 1792713590,
    "memo": "订单备注",
    "businessInfo": "{\"source\":\"example\"}",
    "pricingMode": "APP_TOTAL",
    "paymentProduct": "USER_SCAN_WECHAT_OFFLINE",
    "totalFeeRate": "0.600000",
    "totalFee": "0.60",
    "feeStatus": "CONFIRMED",
    "unSplitAmount": "99.40",
    "unSplitAmountQueriedAt": 1792713600,
    "canDivide": false,
    "availableDivideAmount": null
  }
}

业务响应字段

字段类型必填说明
data.orderIdstring是订单号
data.merchantNostring是收款商户号
data.uniqueOrderNostring是支付流水号，尚未取得时为空。
data.orderAmountstring是订单金额，单位元，十进制字符串。
data.unSplitAmountstring / null是剩余可分账金额，单位元，固定两位小数字符串；null 表示未取得有效金额，不能按 0 处理；0.00 表示已确认没有剩余可分账金额。适用于支付成功后的分账场景，与账户余额不同。
data.unSplitAmountQueriedAtinteger是有效剩余可分账金额的查询时间，Unix 秒时间戳；未取得金额时为 0。金额为此时点的快照，同一订单最多复用 5 秒。
data.statusinteger是订单支付状态：0 待支付、1 已支付、2 失败、3 已取消、4 已过期。状态更新可能延迟；本次剩余金额查询不改变支付状态。
data.payChannelstring是支付渠道：WECHAT / ALIPAY。
data.payWaystring是下单支付方式。
data.platformFeestring是费用处理参考金额，单位元；订单总手续费以 totalFee 为准，费用是否确认见 feeStatus。
data.fundProcessTypestring是接入方业务选择：REAL_TIME / DELAY_SETTLE。
data.fundStatusstring是资金处理状态；DELAY_SETTLE 模式下 RESERVED 表示余款保留待后续处理。
data.notifyStatusstring是向接入方发送支付通知的任务状态，独立于支付状态。
data.paidAtinteger是支付成功的 Unix 秒时间戳，未支付为 0。
data.memostring是下单时的业务备注。
data.businessInfostring是下单时的业务扩展信息，为 JSON 字符串或空字符串。
data.pricingModestring是计费类型：LEGACY 历史计费，APP_TOTAL 应用约定费率计费。 取值：LEGACY / APP_TOTAL。
data.paymentProductstring是本次交易对应的支付产品代码，历史订单可能为空。
data.totalFeeRatestring / null是本次订单适用的总费率，以百分比表示；0.600000 表示 0.6%。历史订单可能为 null。
data.totalFeestring / null是本次订单总手续费，单位元。历史订单可能为 null。
data.feeStatusstring是费用状态：PENDING 待确认，CONFIRMED 已确认，REVIEW 待核对，LEGACY 历史计费。 取值：LEGACY / PENDING / CONFIRMED / REVIEW。
data.canDivideboolean是当前是否具备订单分账条件。金额是查询时点快照，申请时会重新校验；false 时不应提交分账。
data.availableDivideAmountstring / null是当前可申请订单分账的金额，单位元。未具备条件、存在未确认申请或金额未知时为 null；0.00 表示已确认没有可用额度。
/api/open.merchant/accountBalanceQuery 商户全部账户余额查询

POSTContent-Type application/json公共协议 ↗

查询当前应用所属商户的全部账户余额及账户状态。资金账户、待结算账户和待分账账户分别展示，总余额不等于可出款金额。

仅可查询当前应用下的商户。若应用配置了 scope，需授权 open.merchant/accountbalancequery。

金额为查询时点的余额，以两位小数字符串返回。查询余额不代表已完成分账或结算。

无法取得有效金额或查询失败时返回 code=0、data=null；不能把查询失败当成零余额。建议轮询间隔不短于 5 秒。

订单分账使用 orderQuery.unSplitAmount；余额分账使用商户资金账户余额，不能把全部账户总余额、待结算余额或订单可分账金额混用。

FUND_ACCOUNT 表示商户资金账户。余额分账使用资金账户余额，是否可发起仍取决于应用权限、商户产品、账户状态及实际可用资金。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，本接口必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/accountBalanceQuery
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对 merchantNo 及当前应用归属；其他应用和未分配商户均不能查询。
channel 必须填写 yibao200本接口 channel 仅支持 yibao。
merchantNo 必须为有效的商户编号，最多 32 位200merchantNo 必须是字符串，允许字母、数字、下划线和连字符，最多 32 位。
余额查询暂不可用，请稍后重试或联系平台核对商户配置200本次查询未成功，请稍后使用原查询条件重试；不要按零余额处理。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "查询成功",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "totalAccountBalance": "200.37",
    "accountInfoList": [
      {
        "accountType": "FUND_ACCOUNT",
        "balance": "100.37",
        "accountStatus": "AVAILABLE",
        "createTime": "2026-10-01T12:00:00+08:00"
      },
      {
        "accountType": "SETTLE_ACCOUNT",
        "balance": "100.00",
        "accountStatus": "AVAILABLE"
      }
    ],
    "queriedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。
data.totalAccountBalancestring是全部账户总余额，不能作为某一账户的可出款金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.accountInfoListarray是实际返回的账户列表；缺少某类账户不代表其余额为零，不会补造账户。
data.accountInfoList[].accountTypestring是账户类型：SETTLE_ACCOUNT 待结算、FUND_ACCOUNT 商户资金、DIVIDE_ACCOUNT 待分账、FEE_ACCOUNT 手续费、MARKET_ACCOUNT 营销、SPECIAL_FUND_ACCOUNT 专款、DIVIDE_FUND_ACCOUNT 分账资金、DIVIDE_PENDING_ACCOUNT 分账在途。请兼容新增账户类型。 最大 64 个字符。
data.accountInfoList[].balancestring是本账户余额，能否出款还需结合账户状态、产品权限及实际操作结果。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.accountInfoList[].accountStatusstring是账户状态：AVAILABLE 可用、FROZEN 冻结、FROZEN_CREDIT 冻结止收、FROZEN_DEBIT 冻结止付、CANCELLATION 销户。请兼容新增状态。 最大 64 个字符。
data.accountInfoList[].createTimestring否账户开户时间，取得时返回。 最大 64 个字符。
data.queriedAtinteger是本次成功查询的 Unix 秒时间戳。金额仅为查询时点快照，不预占资金。
/api/open.merchant/settleBalanceQuery 商户待结算金额查询

POSTContent-Type application/json公共协议 ↗

查询当前应用所属商户的可结算金额、未结算总额，以及结算产品和账户明细。支持查询当前全部，或按指定截止时间查询。

仅可查询当前应用下的商户。若应用配置了 scope，需授权 open.merchant/settlebalancequery。

金额为查询时点的余额，以两位小数字符串返回。查询余额不代表已完成分账或结算。

无法取得有效金额或查询失败时返回 code=0、data=null；不能把查询失败当成零余额。建议轮询间隔不短于 5 秒。

当前 D1 手动结算产品代码为 D1_MANUAL。可结算时间及金额以本接口结果为准，不能简单按分账时间加 24 小时判断。

settlableAmount 为可结算但未结算金额；unsettledAmount 还包含尚未到结算周期的金额。金额变为零不能据此确认结算成功。

按截止时间查询时，在完整请求中添加 operatePeriod=PERIOD 和 endTime=2026-10-23T23:59:59+08:00，再重新生成签名。该查询不提供历史时点的账户余额回放。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，本接口必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。
operatePeriodstring否ALL 查询当前全部；PERIOD 查询指定截止时间范围。 取值：ALL / PERIOD。 默认："ALL"。
endTimestring条件必填operatePeriod=PERIOD 时必填；ISO 8601 秒精度，必须带时区，如 2026-10-23T23:59:59+08:00，也支持 Z。ALL 时省略。 最大 25 个字符。
tradeChannelstring否交易通道，当前仅支持 YEEPAY。 取值：YEEPAY。 默认："YEEPAY"。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/settleBalanceQuery
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对 merchantNo 及当前应用归属；其他应用和未分配商户均不能查询。
channel 必须填写 yibao200本接口 channel 仅支持 yibao。
merchantNo 必须为有效的商户编号，最多 32 位200merchantNo 必须是字符串，允许字母、数字、下划线和连字符，最多 32 位。
余额查询暂不可用，请稍后重试或联系平台核对商户配置200本次查询未成功，请稍后使用原查询条件重试；不要按零余额处理。
operatePeriod 仅支持 ALL、PERIOD200本阶段不接受 AMOUNT。
PERIOD 必须填写有效 endTime，格式如 2026-10-23T23:59:59+08:00，须含时区200核对日期、时间及有效时区，PERIOD 不可省略。
endTime 仅在 operatePeriod=PERIOD 时填写200ALL 查询省略 endTime。
tradeChannel 当前仅支持 YEEPAY200使用 YEEPAY 或省略 tradeChannel。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "查询成功",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "operatePeriod": "ALL",
    "endTime": null,
    "tradeChannel": "YEEPAY",
    "settlableAmount": "80.10",
    "unsettledAmount": "100.00",
    "detailList": [
      {
        "settleType": "D1_MANUAL",
        "accountType": "SETTLE_ACCOUNT",
        "tradeChannel": "YEEPAY",
        "settlableAmount": "80.10",
        "unsettledAmount": "100.00"
      }
    ],
    "queriedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。
data.operatePeriodstring是本次查询范围。 取值：ALL / PERIOD。
data.endTimestring / null是PERIOD 返回北京时间的截止时间；ALL 返回 null。
data.tradeChannelstring是本次查询的交易通道。 取值：YEEPAY。
data.settlableAmountstring是当前可结算但未结算的金额。变为零不代表结算成功，可能已生成结算记录或本身就没有可结算金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.unsettledAmountstring是未结算总额，包含可结算但未结算金额，以及尚未到结算周期的金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.detailListarray是按结算产品和账户返回的金额明细。
data.detailList[].settleTypestring是结算产品代码，当前使用 D1_MANUAL；请兼容其他已开通产品。 最大 64 个字符。
data.detailList[].accountTypestring是结算账户类型，常见 SETTLE_ACCOUNT 待结算账户、DIVIDE_PENDING_ACCOUNT 分账在途账户、BASIC_ACCOUNT 基本账户。 最大 64 个字符。
data.detailList[].tradeChannelstring是交易通道。 取值：YEEPAY。
data.detailList[].settlableAmountstring是该明细当前可结算金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.detailList[].unsettledAmountstring是该明细未结算总额。 单位元，固定两位小数字符串；如存在负余额会保留负号。
data.queriedAtinteger是本次成功查询的 Unix 秒时间戳。金额仅为查询时点快照，不预占资金。
/api/open.merchant/settleWayQuery 商户结算方式查询

POSTContent-Type application/json公共协议 ↗

查询当前应用所属商户已配置的结算方向及对应比例。一个商户可能有多个方向，按 settleWayList 中各项比例解释。

仅可查询当前签名应用所属的商户；如应用限制 scope，需授权 open.merchant/settlewayquery。

settleWayList 是结算方向列表，不能假定只有一项。BANKCARD 表示银行卡，ACCOUNT 表示资金账户，BANKACCOUNT 表示合作银行账户；兼容 FEE_ACCOUNT 手续费账户和 MARKET_ACCOUNT 营销账户。

settleRatio 单位为百分比，固定两位小数字符串，例如 80.00 表示 80%。请保留各项方向及比例。

成功返回空列表表示本次没有取得已配置的结算方向，不应默认解释为银行卡或资金账户；缺失有效列表、未知方向、异常比例或查询失败时返回 code=0、data=null。

本接口返回结算方向及比例。queriedAt 为本次成功查询的 Unix 秒时间戳。

结算方式、待结算金额、账户余额分别通过 settleWayQuery、settleBalanceQuery、accountBalanceQuery 查询；配置了某种结算方向不代表资金已结算到账。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，本接口必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/settleWayQuery
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对商户编号与当前应用归属，其他应用及未分配商户均不可查询。
channel 必须填写 yibao200本接口仅支持 channel=yibao。
merchantNo 必须为有效的商户编号，最多 32 位200提交字符串商户编号，允许字母、数字、下划线和连字符，最多 32 位。
请使用 POST 请求200按公共协议使用 POST 提交签名请求。
结算方式查询暂不可用，请稍后重试或联系平台核对商户配置200本次查询未成功，请稍后重试；不要将失败结果解释为已设置银行卡结算。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "查询成功",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "settleWayList": [
      {
        "settleWay": "BANKCARD",
        "settleWayName": "银行卡",
        "settleRatio": "80.00"
      },
      {
        "settleWay": "ACCOUNT",
        "settleWayName": "资金账户",
        "settleRatio": "20.00"
      }
    ],
    "queriedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是商户编号，仅可查询当前签名应用所属的商户。 最大 32 个字符。
data.settleWayListarray是已配置的结算方向和比例列表，可能有多项；空列表不代表默认结算至银行卡。
data.settleWayList[].settleWaystring是BANKCARD 银行卡；ACCOUNT 资金账户；BANKACCOUNT 合作银行账户；FEE_ACCOUNT 手续费账户；MARKET_ACCOUNT 营销账户。 取值：BANKCARD / ACCOUNT / BANKACCOUNT / FEE_ACCOUNT / MARKET_ACCOUNT。
data.settleWayList[].settleWayNamestring是结算方向的中文名称，与 settleWay 对应。 取值：银行卡 / 资金账户 / 合作银行账户 / 手续费账户 / 营销账户。
data.settleWayList[].settleRatiostring是该结算方向的比例，单位 %，范围 0.00 至 100.00，固定两位小数字符串。80.00 表示 80%。
data.queriedAtinteger是本次成功查询的 Unix 秒时间戳，结算配置为此时点的快照。
/api/open.merchant/settleWayModifyRatio 修改商户结算方向

POSTContent-Type application/json公共协议 ↗

为当前应用所属商户选择一个结算方向，后续结算时全部资金转至所选目标。每次仅选择一个方向，无需且不允许填写百分比。银行卡和合作银行账号须已添加为结算卡。

仅可修改当前签名应用所属的商户。应用限制 scope 时须授权 open.merchant/settlewaymodifyratio，查询接口授权不等于此修改接口授权。

只提交一个 settleWay，后续结算时全部资金转至所选方向。不得传入 settleRatio、settleWayList 或其他结算方向列表。

例如全部结算至资金账户，填写 settleWay=ACCOUNT；全部结算至已绑定银行卡，填写 settleWay=BANKCARD，并补充该卡的 bankCardNo。

BANKCARD/BANKACCOUNT 须填写已添加为结算卡的完整账号，其他方向省略 bankCardNo；银行卡号须作为字符串传递。

处理成功返回 code=1、data.status=SUCCESS。processedAt 为本次确认时间，不代表资金到账时间；修改后请调用 settleWayQuery 核对配置。

超时或返回“结果未确认”时，修改可能已生效。先查询当前配置并核对目标，再决定是否重新提交；不要直接循环重试。

本接口设置结算方向，不发起资金结算。账户余额、可结算金额分别使用 accountBalanceQuery 和 settleBalanceQuery 查询。

响应不回显账号或户名。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅可修改当前签名应用所属的商户。 最大 32 个字符。
settleWaystring是选择一个结算方向：BANKCARD 银行卡；ACCOUNT 商户资金账户；BANKACCOUNT 合作银行账户；FEE_ACCOUNT 商户手续费账户；MARKET_ACCOUNT 商户营销账户。每次仅选择一个方向，后续结算时全部资金转至所选目标。 取值：BANKCARD / ACCOUNT / BANKACCOUNT / FEE_ACCOUNT / MARKET_ACCOUNT。
bankCardNostring条件必填BANKCARD/BANKACCOUNT 时必填，且已添加为结算卡；其他方向省略。银行卡方向填写已绑定完整卡号；合作银行方向填写开户返回的合作银行账号。禁止填写掩码或数值类型。 最大 64 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/settleWayModifyRatio
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "settleWay": "ACCOUNT"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对 merchantNo 和应用归属，其他应用及未分配商户均不可修改。
channel 必须填写 yibao200填写 channel=yibao。
merchantNo 必须为有效的商户编号，最多 32 位200提交字符串商户编号。
settleWay 必须为单个受支持的结算方向200填写五种已支持方向之一，不能传数组、空值或未知方向。
请求包含不支持的结算比例字段200删除 settleRatio 字段，仅通过 settleWay 选择一个结算方向。
仅允许提交一个 settleWay，请勿传入结算方向列表200删除 settleWayList 及其他结算方向列表，仅提交单个 settleWay。
银行卡或合作银行方向必须填写有效的完整 bankCardNo，最多 64 位200填写已经绑定的完整账号字符串，不能使用掩码。
非银行卡或合作银行方向请省略 bankCardNo200ACCOUNT、FEE_ACCOUNT、MARKET_ACCOUNT 项省略账号字段。
结算账户不存在或未开通200核对目标账号和产品开通情况。
结算修改商户关系校验未通过200联系技术支持核对商户权限。
结算修改请求重复，请先查询当前配置200查询当前配置确认前次结果，避免重复提交。
结算方式修改结果未确认，请先查询当前配置后再决定是否重试200超时、异常响应或状态未确认；不能直接认定修改没有生效。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "修改成功",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "status": "SUCCESS",
    "processedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是本次修改处理的商户编号。 最大 32 个字符。
data.statusstring是本次结算方向修改处理成功。 取值：SUCCESS。
data.processedAtinteger是本次修改处理确认的 Unix 秒时间戳，不是结算到账时间。
/api/open.merchant/selfSettleApply 自助结算申请

POSTContent-Type application/json公共协议 ↗

将待结算账户中当前符合结算条件的资金，按商户已配置的结算方向发起结算。银行卡方向结算至绑定银行卡，ACCOUNT 方向转入资金账户。

仅可操作当前签名应用所属商户；应用限制 scope 时须授权 open.merchant/selfsettleapply。查询权限不代表有申请权限。

先用 settleWayQuery 确认方向，用 settleBalanceQuery 查看可结算资金，再发起申请。申请不会修改结算方向，也不能在请求中指定银行卡或比例。

结算至 BANKCARD 时转至已配置银行卡；结算至 ACCOUNT 时转入商户资金账户。使用其他已配置方向时，以相应账户及记录明细为准。

operatePeriod 默认 ALL，申请结算当前全部符合条件的资金。PERIOD 须填写带时区的 endTime；当前 D1 按结算日切和产品规则处理，不等于交易时间加 24 小时。

D1 示例：endTime=2026-10-24T00:00:00+08:00 表示按该结算日的可结算范围处理；实际可结算金额及是否可处理，以查询和申请结果为准。

每笔业务由你方生成固定且唯一的 settleRequestNo。nonce 是每次 HTTP 请求的防重放随机串，不能代替业务请求号；查询原申请时继续使用原 settleRequestNo。

code=1、data.status=ACCEPTED 只表示已受理，尚未确认结算成功或到账。最终结果请调用 settleRecordsQuery，结合记录状态和到账明细判断。

超时、重复请求或受理结果未确认时，先按原 settleRequestNo 查询。不要更换业务请求号再次申请，也不要自动循环重试；记录暂未查到时不能认定原申请失败。

这是待结算资金的自助结算；已进入资金账户的余额提现是另一项能力。接口只返回受理信息，不把申请金额填作实际到账金额。

notifyUrl 为接收结算结果通知的公网 HTTP(S) 地址。选填；省略或为空字符串时不发送通知，可通过 settleRecordsQuery 查询结果。

同一商户内的 settleRequestNo 须唯一。同一应用使用相同请求号和业务参数重复调用时返回原受理信息；参数不一致时拒绝。结果未确认时继续使用原号查询。

通知可能重复或乱序。使用 notify_id 去重，并记录同一结算申请的最新 version；重复通知直接确认，较低版本不得覆盖新状态。

结算成功后发生冲退时，会收到更高版本的 RETREATED 通知，retreatFlag=true；请按新版本更新业务状态。

结算结果通知采用 POST JSON，签名方式与本次申请一致：HMAC-SHA256 使用应用密钥验签，RSA2 使用平台提供的通知公钥验签。同一版本的业务内容和 notify_id 不变；每次通知的 timestamp、nonce、sign 可能不同。

通知成功应答为 HTTP 2xx 与纯文本 SUCCESS；同一通知最多自动投递 10 次（含首次），失败等待间隔为 10、20、40、80、160、320、640、1280、2560 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅限当前签名应用所属的商户。 最大 32 个字符。
settleRequestNostring是接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。 最大 64 个字符。
operatePeriodstring否ALL 申请结算当前全部可结算资金；PERIOD 申请结算截至指定时间的可结算资金。当前不开放指定金额结算。 取值：ALL / PERIOD。 默认："ALL"。
endTimestring条件必填PERIOD 时必填；带时区的截止时间，例 2026-10-24T00:00:00+08:00；ALL 时省略。
bankRemarkstring否银行附言，最多 32 字，不能包含换行或控制字符。 最大 32 个字符。
notifyUrlstring否接收结算结果通知的公网 HTTP(S) 地址。选填；省略或为空字符串时不发送通知，可通过 settleRecordsQuery 查询结果。 最大 2048 个字符。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/selfSettleApply
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "settleRequestNo": "SETTLE_20261024_0001",
  "operatePeriod": "ALL",
  "notifyUrl": "https://partner.example.com/notify/settlement"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对商户编号和当前应用归属。
settleRequestNo 必须为 1 至 64 位字母、数字、下划线或连字符200提交商户内唯一、格式有效的字符串请求号。
operatePeriod 仅支持 ALL、PERIOD200当前仅开放全部可结算资金和按截止时间结算，不支持 AMOUNT。
自助结算申请不支持参数 <字段>，请按接口文档提交200删除指定金额、方向、账号、extInfo、receiverMerchantNo 等未开放字段；notifyUrl 按字段要求填写。
endTime 仅在 operatePeriod=PERIOD 时填写200ALL 请求省略 endTime；PERIOD 必须填写。
endTime 必须为带时区的 ISO 8601 秒精度时间200填写有效日期及明确时区，不支持无时区或毫秒。
bankRemark 必须为不超过 32 字的单行字符串200缩短附言并移除控制字符。
当前范围内无可结算明细200先查询可结算金额和产品周期；不代表商户账户没有余额。
可结算账户余额不足200核对实时可结算资金及近期结算申请。
结算金额未达起结金额200确认产品的起结金额规则。
结算请求号重复，请使用原请求号查询结算记录200查询原申请；不要换号重新申请。
结算申请受理结果未确认，请使用原 settleRequestNo 查询结算记录，勿换号重试200原申请可能已被受理，先查询和核对。
settleRequestNo 已存在且归属或业务参数不一致200原业务请求号不得换应用或修改参数后再次申请；查询并核对原申请。
notifyUrl 必须为字符串 / notifyUrl 地址无效200可省略、留空字符串或填写符合要求的公网 HTTP(S) 地址，不接受 null、私网、保留地址或跳转目标。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "结算申请已受理，请查询最终结果",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "settleRequestNo": "SETTLE_20261024_0001",
    "settleOrderNo": "SETTLE_ORDER_EXAMPLE",
    "status": "ACCEPTED",
    "acceptedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是商户编号，仅限当前签名应用所属的商户。 最大 32 个字符。
data.settleRequestNostring是接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。 最大 64 个字符。
data.settleOrderNostring是本次受理返回的结算订单号。 最大 64 个字符。
data.statusstring是ACCEPTED 仅表示结算申请已受理，不能据此标记到账。 取值：ACCEPTED。
data.acceptedAtinteger是本次受理确认时间，Unix 秒时间戳。

结算结果通知

通知采用 POST application/json。请先验签、核对商户及原请求号，使用 notify_id 去重，并按 version 处理通知顺序。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试；同一版本的业务内容不变，timestamp、nonce、sign 可能不同。

通知字段

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
notify_idstring是固定通知事件标识，重试不变；请持久化去重。 最大 64 个字符。
eventTypestring是结算结果通知类型。 取值：SETTLEMENT_RESULT。
versioninteger是同一商户、结算请求的单调递增通知版本；仅允许更高版本更新状态。
merchantNostring是原申请商户编号。
settleRequestNostring是原结算业务请求号。
settleOrderNostring是已核实的结算订单号。
settleStatusstring是SUCCESS 结算成功；SETTLE_FAIL 结算异常；RETREATED 已发生打款冲退，不能作为资金仍到账处理。 取值：SUCCESS / SETTLE_FAIL / RETREATED。
settleAmountstring是应结金额，单位元，固定两位小数。
realAmountstring / null是结算到账金额，元；未取得时为 null，不默认等于应结金额。
feeAmountstring / null是结算手续费，元；未知时为 null，明确为零时为 0.00。
retreatFlagboolean / null是true 表示冲退；false 表示本次明确未冲退；null 表示未取得标记。
settleTypestring / null是结算产品；以本次记录为准，未返回时为 null。 最大 64 个字符。
detailListarray / null是全部到账明细，不折叠为其中一条；未取得明细列表时为 null，返回空列表时保持为空。
detailList[].statusstring是到账明细状态：INIT 待处理；REMIT_PROCESS 银行处理中；REMIT_FAIL/ACCOUNTING_FAIL 出款失败；REMIT_SUCCESS/SUCCESS 已到账。 取值：INIT / REMIT_PROCESS / REMIT_FAIL / ACCOUNTING_FAIL / REMIT_SUCCESS / SUCCESS。
detailList[].statusNamestring是该明细状态的中文名称。
detailList[].realAmountstring / null是该明细到账金额，元；未知时为 null，明确为零时为 0.00。
detailList[].accountTypestring / null是目标账户类型：DEBIT_CARD 借记卡、PUBLIC_CARD 对公账户、PASSBOOK 存折、UNIT_SETTLE_CARD 单位结算卡、BANKACCOUNT 银行账户、FEE_ACCOUNT 手续费账户、MARKET_ACCOUNT 营销账户、ACCOUNT 资金账户；未知时为 null。 最大 64 个字符。
detailList[].correctboolean / null是是否打款冲退。true 表示该笔发生冲退，不能仅凭成功状态判断资金仍已到账；null 表示未取得冲退标记。
detailList[].finishTimestring / null是到账完成时间，未返回时为 null；保留查询结果时间文本。 最大 64 个字符。
detailList[].reverseTimestring / null是冲退时间，未返回时为 null。 最大 64 个字符。
occurredAtinteger是本版本结果的确认时间，Unix 秒时间戳；重试时不变。timestamp 为本次通知发送时间。

通知结构示例

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "本次投递生成的新随机串",
  "sign": "平台对全部参数生成签名",
  "notify_id": "SN0000000000000000000000000000000000000000",
  "eventType": "SETTLEMENT_RESULT",
  "version": 1,
  "merchantNo": "10000000002",
  "settleRequestNo": "SETTLE_20261024_0001",
  "settleOrderNo": "SETTLE_ORDER_EXAMPLE",
  "settleStatus": "SUCCESS",
  "settleAmount": "100.00",
  "realAmount": null,
  "feeAmount": "0.00",
  "retreatFlag": false,
  "settleType": "D1_MANUAL",
  "detailList": null,
  "occurredAt": 1792800000
}

请先验签，核对业务请求及金额，使用 notify_id 去重；通知包含 version 时，较低版本不得覆盖新状态，包含 detailId 时须分别比较每笔明细的版本。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS（大小写均可）。通知失败会重试，请避免重复发货或记账。

$payload = json_decode(file_get_contents('php://input'), true);
// HMAC 使用 app_secret；RSA2 第三个参数传平台提供的通知公钥。
$verified = is_array($payload) && $client->verifyNotification($payload, $platformPublicKey ?? '');
// 验签通过后，核对业务请求及金额，完成业务处理和通知去重，再应答 SUCCESS。

异步通知完整指南 ↗ · 成功确认与停止规则 ↗ · 最多 10 次投递及失败间隔 ↗

/api/open.merchant/settleRecordsQuery 结算记录查询

POSTContent-Type application/json公共协议 ↗

按原结算请求号，或按结算申请起止时间，查询当前应用所属商户的结算处理结果、到账明细和冲退情况。

仅可查询当前签名应用所属商户；应用限制 scope 时须授权 open.merchant/settlerecordsquery。

查询原申请结果优先填写 settleRequestNo。按时间查询时同时填写 settleRequestBeginTime、settleRequestEndTime，两者按申请时间筛选，每次范围不能超过 31 天；两种条件也可同时提交。

时间输入使用带时区的 ISO 8601 秒精度格式，例如 2026-10-24T00:00:00+08:00；不接受无条件拉取全部历史记录。

code=1 仅表示本次查询成功。实际结算状态看 settleRecordList[].status；到账状态、目标账户类型和冲退标记还要查看各记录的 detailList。

BEFORE_REMIT 和 REMITTING 属于处理中，不能标记到账。SETTLE_FAIL 为结算异常；SUCCESS 仍应结合到账明细及 correct 冲退标记处理，correct=true 时不能视为资金仍到账。

记录和到账明细可能有多条，请完整处理列表，不要只取第一条记录代表整笔结算。

所有金额均为元、固定两位小数字符串；未知到账金额、手续费和未返回的可选字段为 null，不猜测为零或应结金额。

空记录列表、查询失败、记录暂不可见均不能证明原申请失败，也不能作为换号再次申请的依据。请用原请求号继续查询或联系平台核对。

结算申请仅限原发起应用查询；商户关联至其他应用后，其他应用也不能读取原申请记录。

结算结果发送至 selfSettleApply 时填写的 notifyUrl；未收到通知或需要确认结果时，请主动查询。

业务参数

参数类型必填 / 位置说明
channelstring是渠道标识，必填 yibao。 取值：yibao。
merchantNostring是商户编号，仅限当前签名应用所属的商户。 最大 32 个字符。
settleRequestNostring二选一接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。 最大 64 个字符。
settleRequestBeginTimestring条件必填结算申请起始时间；按时间查询时与截止时间一起填写，范围不超过 31 天。
settleRequestEndTimestring条件必填结算申请截止时间；不能早于起始时间。
tradeChannelstring否当前仅支持 YEEPAY，可省略。 取值：YEEPAY。 默认："YEEPAY"。

上表只列业务字段；完整请求还包含 app_id、timestamp、nonce、sign，sign_type 可省略。先合并全部参数，再计算签名。

请替换示例中的域名、应用凭据及业务数据；时间戳、随机串和签名由公共客户端生成。

完整请求示例

POST /api/open.merchant/settleRecordsQuery
Content-Type: application/json

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "每次请求生成新随机串",
  "sign": "请在服务端生成签名",
  "channel": "yibao",
  "merchantNo": "10000000002",
  "settleRequestNo": "SETTLE_20261024_0001"
}

业务错误与处理

msg / 情况HTTP处理说明
商户不存在或无权访问200核对当前应用的商户归属。
请填写 settleRequestNo，或同时填写结算申请起止时间200选择原请求号查询，或填写完整时间范围。
settleRequestNo 必须为 1 至 64 位字母、数字、下划线或连字符200使用发起申请时的原业务请求号。
结算申请时间范围须按先后填写且不能超过 31 天200缩小时间范围并核对先后顺序。
settleRequestBeginTime / settleRequestEndTime 必须为带时区的 ISO 8601 秒精度时间200提供有效日期和明确时区，不支持无时区、毫秒或空值。
tradeChannel 当前仅支持 YEEPAY200省略该参数或填写 YEEPAY。
本接口不支持 receiverMerchantNo200删除该参数，仅查询当前应用商户。
结算记录查询暂不可用，请稍后重试或联系平台核对200查询失败或暂未查到记录不代表结算申请失败，请继续使用原请求号核对结果。

HTTP 200 时仍需检查 code；HTTP 401 请核对应用凭据与签名，HTTP 503 请稍后重试。

响应示例

{
  "code": 1,
  "msg": "查询成功",
  "time": "1792800000",
  "data": {
    "merchantNo": "10000000002",
    "settleRequestNo": "SETTLE_20261024_0001",
    "tradeChannel": "YEEPAY",
    "settleRecordList": [
      {
        "summaryNo": "SETTLE_RECORD_EXAMPLE",
        "status": "SUCCESS",
        "statusName": "结算成功",
        "settleAmount": "100.00",
        "realAmount": "100.00",
        "realFee": "0.00",
        "createTime": "2026-10-24 00:05:00",
        "settleType": "D1_MANUAL",
        "detailList": [
          {
            "status": "SUCCESS",
            "statusName": "已到账",
            "realAmount": "100.00",
            "accountType": "ACCOUNT",
            "correct": false,
            "finishTime": "2026-10-24 00:05:30",
            "reverseTime": null
          }
        ]
      }
    ],
    "queriedAt": 1792800000
  }
}

业务响应字段

字段类型必填说明
data.merchantNostring是商户编号，仅限当前签名应用所属的商户。 最大 32 个字符。
data.settleRequestNostring / null是接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。 最大 64 个字符。
data.tradeChannelstring是本次查询交易通道。 取值：YEEPAY。
data.settleRecordListarray是本次条件下返回的全部结算记录；空列表表示暂未查到，不能据此认定申请失败。
data.settleRecordList[].summaryNostring是结算记录订单号。 最大 64 个字符。
data.settleRecordList[].statusstring是结算订单状态：SUCCESS 结算成功；BEFORE_REMIT 待出款；SETTLE_FAIL 结算异常；REMITTING 银行处理中。 取值：SUCCESS / BEFORE_REMIT / SETTLE_FAIL / REMITTING。
data.settleRecordList[].statusNamestring是结算订单状态的中文名称。
data.settleRecordList[].settleAmountstring是应结金额，单位元，固定两位小数。
data.settleRecordList[].realAmountstring / null是结算到账金额，元；未取得时为 null，不默认等于应结金额。
data.settleRecordList[].realFeestring / null是结算手续费，元；未知时为 null，明确为零时为 0.00。
data.settleRecordList[].createTimestring / null是结算订单创建时间，未返回时为 null。 最大 64 个字符。
data.settleRecordList[].settleTypestring / null是结算产品；以本次记录为准，未返回时为 null。 最大 64 个字符。
data.settleRecordList[].detailListarray / null是全部到账明细，不折叠为其中一条；未取得明细列表时为 null，返回空列表时保持为空。
data.settleRecordList[].detailList[].statusstring是到账明细状态：INIT 待处理；REMIT_PROCESS 银行处理中；REMIT_FAIL/ACCOUNTING_FAIL 出款失败；REMIT_SUCCESS/SUCCESS 已到账。 取值：INIT / REMIT_PROCESS / REMIT_FAIL / ACCOUNTING_FAIL / REMIT_SUCCESS / SUCCESS。
data.settleRecordList[].detailList[].statusNamestring是该明细状态的中文名称。
data.settleRecordList[].detailList[].realAmountstring / null是该明细到账金额，元；未知时为 null，明确为零时为 0.00。
data.settleRecordList[].detailList[].accountTypestring / null是目标账户类型：DEBIT_CARD 借记卡、PUBLIC_CARD 对公账户、PASSBOOK 存折、UNIT_SETTLE_CARD 单位结算卡、BANKACCOUNT 银行账户、FEE_ACCOUNT 手续费账户、MARKET_ACCOUNT 营销账户、ACCOUNT 资金账户；未知时为 null。 最大 64 个字符。
data.settleRecordList[].detailList[].correctboolean / null是是否打款冲退。true 表示该笔发生冲退，不能仅凭成功状态判断资金仍已到账；null 表示未取得冲退标记。
data.settleRecordList[].detailList[].finishTimestring / null是到账完成时间，未返回时为 null；保留查询结果时间文本。 最大 64 个字符。
data.settleRecordList[].detailList[].reverseTimestring / null是冲退时间，未返回时为 null。 最大 64 个字符。
data.queriedAtinteger是本次查询时间，Unix 秒时间戳。

Payment

进件之后：下单与分账

商户须完成进件、相应签署与支付产品开通。下单复用公共鉴权，按支付方式补充业务参数；下单受理与最终付款结果需分别判断。

01

前置条件

商户须已进件成功并开通所选支付产品。使用 registerQry 查询进件结果，保存收款商户号。

merchantNo 就是 registerQry 返回的 merchantNo，与进件时平台返回的 outMchNo 不是同一个值，切勿混用。

调用前确认应用与收款商户已开通对应支付能力；收费按应用约定执行，无需在下单参数中填写费率。

02

选择支付方式

同一个 prePay 接口，使用 payChannel 选择 WECHAT 或 ALIPAY，使用 payWay 区分受理形态。返回统一放在 data.response_arr，但形态不同。

payWay形态必填说明
USER_SCAN微信 / 支付宝主扫基础业务参数payChannel 选择支付渠道，返回二维码内容字符串
WECHAT_OFFIACCOUNT微信公众号 JSAPI+ appId、userId返回微信调起参数对象；userId 为付款人 openId
MINI_PROGRAM微信 / 支付宝小程序+ appId、userId显式填写 payChannel；返回小程序支付调起参数
SDK_PAY微信 APP SDK+ appId不强制传 userId；使用返回参数调用微信支付 SDK
ALIPAY_LIFE支付宝生活号+ appId、userId返回支付宝调起参数对象；userId 为支付宝 userId
H5_PAY支付宝 H5基础业务参数payChannel 填写 ALIPAY，返回支付跳转链接

公众号、小程序和生活号必须传 appId 和 userId；微信 SDK 必须传 appId。支付应用 appId 与开放平台凭证 app_id 不同。

03

发起一笔下单

公共参数与业务参数平铺提交，签名规则与进件接口完全一致。

POST /api/open.merchant/prePayapplication/json
{
  "app_id": "ak_********",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1786777149",
  "nonce": "9f3c1a2b4d5e6f70",

  "channel": "yibao",
  "merchantNo": "10093518558",
  "orderId": "SH20261022000001",
  "orderAmount": "0.01",
  "payChannel": "WECHAT",
  "payWay": "USER_SCAN",
  "goodsName": "测试商品",
  "scene": "OFFLINE",

  "sign": "****"
}
pay.php下单并区分返回形态
$result = $client->request('/api/open.merchant/prePay', [
    'channel' => 'yibao',
    'merchantNo' => $merchantNo,
    'orderId' => $yourOrderNo,
    'orderAmount' => '0.01',
    'payChannel' => 'WECHAT',
    'payWay' => 'USER_SCAN',
    'goodsName' => '测试商品',
]);
if ($result['http_status'] !== 200 || $result['body']['code'] !== 1) {
    throw new RuntimeException($result['body']['msg']);
}
$data = $result['body']['data'];
// USER_SCAN 的 response_arr 为二维码内容；下单成功不等于支付成功。

金额单位是元，不是分；scene 默认 OFFLINE。微信支持 ONLINE / OFFLINE，支付宝支持 OFFLINE；应用与商户须已开通所选场景的支付产品。

04

接收支付结果

下单时填写 notifyUrl，支付成功后系统会向该地址发送签名通知。

收到通知后先验签，再核对订单号与金额，按 notify_id 去重处理业务。处理成功后返回纯文本 SUCCESS；备注和业务扩展信息将原样返回。

也可调用 orderQuery 或登录接入控制台查询订单。状态更新可能有延迟，不能仅凭支付页面跳转判定付款成功。

05

选择资金处理方式

fundProcessType 默认 REAL_TIME，支付成功后自动处理费用并释放商户余款。

DELAY_SETTLE 保留订单余款。查询 orderQuery 确认可分账后，可调用 orderDivide 按金额分配；未分配余款继续保留，完结分账暂未开放。

支付成功以签名通知或订单查询为准，不以资金处理完成与否作为付款成功条件。

Integration

一个公共客户端，按接口填写业务参数

公共协议只实现一次；各接口更换路径与业务参数。以下为企业进件示例，资料必须替换，渠道受理结果仍需实际联调确认。

下载公共 PHP 客户端 ↗ · 下载独立开放接口规范 ↗

01

只配置一次公共客户端

下载客户端并保存为 OpenApiClient.php。HMAC 使用 app_secret；RSA2 使用你方私钥并将第四个构造参数设为 RSA2。每次调用都会自动生成时间戳、nonce 和签名。

<?php
require __DIR__ . '/OpenApiClient.php';
$client = new OpenApiClient('https://你的域名', '你的 app_id', '你的 app_secret');
$result = $client->request('/api/open.ping/index', ['echo' => 'hello']);
if ($result['http_status'] !== 200 || $result['body']['code'] !== 1) {
    throw new RuntimeException($result['body']['msg']);
}

02

上传资料并保存路径

逐张上传实际资料。文件内容不参与签名，客户端自动使用 multipart；其他接口继续使用 JSON。下例仅演示上传一张，其余资料按同样方式处理。

$result = $client->request('/api/open.merchant/upload', [], [], [
    'file' => __DIR__ . '/legal-front.jpg',
]);
if ($result['http_status'] !== 200 || $result['body']['code'] !== 1) {
    throw new RuntimeException($result['body']['msg']);
}
$legalFrontUrl = $result['body']['data']['url'];

03

只填写本接口的业务参数

下载企业进件业务参数 JSON，替换真实资料、字典编码和全部上传路径。经营地址必须位于 channel_extra.addressBuss；productRates 必须按所选产品逐项填写等于所属应用当前配置的费用，示例费率请替换；完整字段和主体条件见 register。模板不包含公共参数，客户端会自动添加。

$business = json_decode(
    file_get_contents(__DIR__ . '/register-business.json'),
    true, 512, JSON_THROW_ON_ERROR
);
$business['path']['legalFrontPic'] = $legalFrontUrl;
// 其他资料图片同样替换为真实上传结果；不要提交模板占位资料。
$result = $client->request('/api/open.merchant/register', $business);
if ($result['http_status'] !== 200 || $result['body']['code'] !== 1) {
    throw new RuntimeException($result['body']['msg']);
}
$outMchNo = $result['body']['data']['outMchNo']; // 保存到你方数据库

04

查询状态，业务条件按接口判断

每个后续请求仍由客户端独立签名，不复用旧 nonce。registerQry 的 requestNo 填前一步取得的 outMchNo；进件受理和进件成功是不同状态。

$result = $client->request('/api/open.merchant/registerQry', [
    'channel' => 'yibao',
    'requestNo' => $outMchNo,
]);
if ($result['http_status'] !== 200 || $result['body']['code'] !== 1) {
    throw new RuntimeException($result['body']['msg']);
}
$state = (string)$result['body']['data']['applicationStatus'];
if ($state === '1') {
    $merchantNo = $result['body']['data']['merchantNo'];
    // 按产品开通情况准备支付参数；支付最终结果需另行核对。
}

Notifications

异步通知：接收、验签与结果确认

集中查看支付、订单分账、余额分账和自助结算通知。按通知类型核对业务、处理重复与乱序，再返回成功应答；通知未送达时使用对应查询接口核对结果。

成功应答结束当前通知的自动投递。支付成功仅确认付款，不代表分账或结算完成。进件结果回调使用单独协议 ↗

01 · 通知类型与对应参数

通知类型通知粒度发起接口
支付成功通知 ↗每笔支付成功/api/open.merchant/prePay
订单分账结果通知 ↗按申请整批通知/api/open.merchant/orderDivide
余额分账结果通知 ↗按分账明细逐笔通知/api/open.merchant/balanceDivide
自助结算结果通知 ↗按结算申请及结果版本通知/api/open.merchant/selfSettleApply

以下通知发送至对应业务请求中的 notifyUrl，使用 POST application/json，字段位于 JSON 顶层。进件使用 callbackurl 和表单格式，见本章后的进件结果回调，不适用以下重试约定。

02 · 什么响应表示接收成功、什么时候停止通知

接入方响应判定后续行为
HTTP 200，正文 SUCCESS接收成功推荐应答；确认后结束当前 notify_id 的自动投递。
其他 HTTP 2xx，正文 success / Success接收成功正文忽略大小写并去除首尾空白；建议统一返回大写 SUCCESS。
HTTP 2xx，正文为空、FAIL、STOP、PAUSE 或 JSON接收失败即使 HTTP 成功，也不会确认通知；按剩余次数重试。
HTTP 非 2xx、网络错误或超时接收失败即使正文为 SUCCESS 也不会确认通知；按剩余次数重试。
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

SUCCESS

SUCCESS 表示业务已可靠处理，或已确认是重复／旧版本并安全忽略。它只结束当前通知，不会关闭该商户或该业务后续的新版本通知。

目前没有暂停或恢复通知的开放接口，也不识别 PAUSE、STOP、Retry-After 等暂停指令。返回失败只会触发有限重试，不能当作无限期暂停。

如果不需要通知，请在创建对应业务时省略 notifyUrl 或填写空字符串；这不是对已创建业务的暂停操作。

03 · 自动投递次数、失败间隔和超时

同一 notify_id 最多自动投递 10 次，包含首次投递，即最多自动重试 9 次。失败后的等待间隔如下，每次从上一次投递失败后起算，不是从首次投递开始累计。

第几次投递距上次失败的等待间隔
第 2 次投递10 秒
第 3 次投递20 秒
第 4 次投递40 秒
第 5 次投递80 秒（1 分 20 秒）
第 6 次投递160 秒（2 分 40 秒）
第 7 次投递320 秒（5 分 20 秒）
第 8 次投递640 秒（10 分 40 秒）
第 9 次投递1280 秒（21 分 20 秒）
第 10 次投递2560 秒（42 分 40 秒）

通知 HTTP 请求总超时为 15 秒。上述间隔是失败后的计划等待时间，实际到达时间可能因网络或服务繁忙而推迟，不承诺精确到秒。

首次及后续某次投递一旦收到成功应答，当前通知即不再重试。达到最大次数后停止自动投递；此时请使用对应结果查询接口核对业务，不要将通知失败当作支付或分账失败，也不要换请求号重新发起资金申请。

04 · 验签、去重与版本

先用公共客户端 verifyNotification 验证应用、签名算法、签名及当前时间。HMAC-SHA256 使用应用密钥；RSA2 使用通知公钥。收到通知后仍须核对本地业务归属、商户、请求号和金额。

通知类型接入方处理要求
支付成功按 app_id + notify_id 去重，核对 orderId、merchantNo、orderAmount；付款成功不表示分账完成。
订单分账按 app_id + notify_id 去重；按 merchantNo + orderId + divideRequestId 比较 version，读取整批 detailList。
余额分账按 app_id + notify_id 去重；按 merchantNo + divideRequestId + detailId 分别比较 version；冲退可能产生更高版本。
自助结算按 app_id + notify_id 去重；按 merchantNo + settleRequestNo 比较 version；冲退以更高版本结果处理。

同一通知重试时，notify_id 和业务内容不变；timestamp、nonce、sign 会重新生成。结果变化产生新通知及新的 notify_id，较低版本不得覆盖同一业务或明细的较高版本。金额为 null 时表示未确认，不能按 0 记账。

05 · 接收端参考代码

下载公共客户端 ↗ · 下载通知 HTTP 接收函数 ↗

接收函数负责解析、验签和 HTTP 应答。你方须实现 notification-business.php，返回一个可调用的业务处理函数：在同一事务中核对业务、处理 notify_id 去重和 version、保存业务结果及已处理标记；成功或重复／旧版本已安全忽略后返回 true，处理失败返回 false 或抛异常。示例不会替你完成这些业务步骤。

<?php
require __DIR__ . '/OpenApiClient.php';
require __DIR__ . '/NotificationReceiver.php';

// 凭据保存在你方服务器，算法与应用配置一致。
$signType = 'HMAC-SHA256'; // RSA2 应用改为 RSA2。
$client = new OpenApiClient('https://你的域名', '你的 app_id', '你的 app_secret', $signType);
// RSA2 时填写平台提供的通知公钥，HMAC 时留空。
$platformPublicKey = '';
$handleBusiness = require __DIR__ . '/notification-business.php';
if (!is_callable($handleBusiness)) {
    http_response_code(503);
    header('Content-Type: text/plain; charset=utf-8');
    exit('FAIL');
}
$result = receiveOpenNotification(
    file_get_contents('php://input'), $client, $handleBusiness, $platformPublicKey
);
http_response_code($result['http_status']);
header('Content-Type: text/plain; charset=utf-8');
echo $result['body'];

06 · 各类通知参数与 JSON 示例

支付成功通知 · 每笔支付成功

支付成功后，下单时填写的 notifyUrl 将收到 POST JSON 通知。通知签名方式与下单请求一致；HMAC-SHA256 使用应用密钥验签，RSA2 使用平台提供的通知公钥验签。重复通知使用同一 notify_id，请在业务处理成功后返回 SUCCESS。

接入方收到的参数

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
notify_idstring是固定通知标识，重试时不变；请使用此字段去重，避免重复处理业务。
orderIdstring是订单号，对应下单时的 orderId；下单未传时为返回的生成值。
merchantNostring是收款商户号。
orderAmountstring是原订单金额，单位元，两位小数；须与接入方订单核对。
statusstring是SUCCESS 表示该订单支付成功；请核对订单号与金额后处理业务。 取值：SUCCESS。
uniqueOrderNostring是支付流水号，可用于核对交易。
paidTimestring是支付成功时间，北京时间 yyyy-MM-dd HH:mm:ss。
payChannelstring是本次支付渠道：WECHAT 微信，ALIPAY 支付宝。 取值：WECHAT / ALIPAY。
payWaystring是本次订单的支付方式，与下单请求一致。 取值：USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY / ALIPAY_LIFE / H5_PAY。
fundProcessTypestring是下单时选择的资金处理方式。 取值：REAL_TIME / DELAY_SETTLE。 默认："REAL_TIME"。
memostring是下单时提交的业务备注原值。 最大 256 个字符。
businessInfostring是下单时提交的 businessInfo 原始 JSON 字符串。 最大 4096 个字符。

通知 JSON 示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "本次通知生成的随机串",
  "notify_id": "N_example_stable_notification_id",
  "orderId": "SH20261023000001",
  "merchantNo": "10000000002",
  "orderAmount": "100.00",
  "status": "SUCCESS",
  "uniqueOrderNo": "1001202610230000001",
  "paidTime": "2026-10-23 17:00:00",
  "payChannel": "WECHAT",
  "payWay": "USER_SCAN",
  "fundProcessType": "REAL_TIME",
  "memo": "外部订单备注",
  "businessInfo": "{\"externalOrderId\":\"EXT202610230001\"}",
  "sign": "平台使用应用凭证生成的通知签名"
}

处理成功返回纯文本 SUCCESS。成功应答规则 ↗ · 重试次数与间隔 ↗

订单分账结果通知 · 按申请整批通知

每次申请按整批发送最终结果。通知签名方式与原申请一致：HMAC-SHA256 使用应用密钥验签，RSA2 使用通知公钥验签。收到较低版本或重复通知时，不重复记账。

接入方收到的参数

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
orderIdstring是原支付订单号。
merchantNostring是收款商户编号。
divideRequestIdstring是你方分账请求号。
statusstring是本批分账最终状态。 取值：SUCCESS / FAIL。
totalAmountstring是申请分账总金额，单位元。
detailCountinteger是本次申请的明细笔数。
acceptedAtinteger是申请受理时间，Unix 秒。
versioninteger是结果版本，按同一 orderId、divideRequestId 比较。
feeAmountstring / null是本批实际分账手续费合计；任何明细未确认时为 null。
receiveAmountstring / null是本批实际入账金额合计；任何明细未确认时为 null。
finishTimestring / null是分账完成时间；尚未取得为 null。
detailListarray是本批分账全部明细，每项包含接收商户、申请金额、实际手续费及实际入账金额。
detailList[].detailIdstring是分账明细标识。
detailList[].detailNostring / null是分账成功后的明细流水号；尚未取得为 null。
detailList[].ledgerNostring是接收商户编号。
detailList[].ledgerTypestring是商户间分账。 取值：MERCHANT2MERCHANT。
detailList[].amountstring是申请金额，单位元。
detailList[].feeAmountstring / null是实际分账手续费，单位元；null 表示尚未确认。
detailList[].receiveAmountstring / null是实际入账金额，单位元；null 表示尚未确认。
detailList[].divideDetailDescstring是本笔分账说明。
notify_idstring是通知唯一标识，重复通知保持不变。
eventTypestring是通知类型。 取值：ORDER_DIVIDE_RESULT。

通知 JSON 示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "运行时生成",
  "nonce": "每次请求生成新随机串",
  "orderId": "ORDER_20261025_0001",
  "merchantNo": "10000000002",
  "divideRequestId": "DIVIDE_20261025_0001",
  "status": "SUCCESS",
  "totalAmount": "10.37",
  "detailCount": 1,
  "acceptedAt": 1792922400,
  "version": 1,
  "feeAmount": "0.02",
  "receiveAmount": "10.37",
  "finishTime": "2026-10-25 18:00:00",
  "detailList": [
    {
      "detailId": "OIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "detailNo": "DIVIDE_DETAIL_EXAMPLE",
      "ledgerNo": "10000000003",
      "ledgerType": "MERCHANT2MERCHANT",
      "amount": "10.37",
      "feeAmount": "0.02",
      "receiveAmount": "10.37",
      "divideDetailDesc": "供应商结算"
    }
  ],
  "notify_id": "ONbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "eventType": "ORDER_DIVIDE_RESULT",
  "sign": "由实际通知参数计算"
}

处理成功返回纯文本 SUCCESS。成功应答规则 ↗ · 重试次数与间隔 ↗

余额分账结果通知 · 按分账明细逐笔通知

通知采用 POST application/json，签名方式与申请一致。HMAC-SHA256 使用应用密钥验签；RSA2 使用通知公钥验签。核对商户、请求号、明细和金额，按 notify_id 去重、按 detailId 分别比较 version。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试，同一版本的业务内容不变。

接入方收到的参数

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
detailIdstring是稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。 最大 64 个字符。
detailNostring / null是分账处理明细号，尚未取得时为 null。 最大 64 个字符。
ledgerNostring是接收商户号。 最大 16 个字符。
ledgerTypestring是接收方类型。 取值：MERCHANT。
divideAmountstring是申请分账金额，单位元。
feeChargeSidestring是本笔申请的手续费承担方式。 取值：OUTSIDE / INSIDE。
statusstring是单笔处理状态；成功后发生冲退时仍可能变为 FAIL。 取值：SUCCESS / FAIL。
reversedboolean是是否已确认本笔分账曾成功、之后转为失败。
versioninteger是同一 detailId 内递增的通知版本，从 1 开始；不同明细分别比较，较低版本不得覆盖新状态。
receiveAmountstring / null是实际到账金额；尚未确认时为 null，不得按申请金额或零推算。
debitAmountstring / null是实际扣账金额；尚未确认时为 null。
feeAmountstring / null是实际分账手续费；尚未确认时为 null。
finishTimestring / null是结果中返回的完成时间；尚未取得时为 null。
failReasonstring是失败原因，无失败原因时为空字符串。
remarkstring是申请时填写的附言。
divideReasonstring是申请时填写的分账说明。
notify_idstring是固定通知标识，重试不变。
eventTypestring是通知类型。 取值：BALANCE_DIVIDE_RESULT。
merchantNostring是原出款商户号。
divideRequestIdstring是原分账请求号。
occurredAtinteger是本版本结果的确认时间，Unix 秒时间戳；重试时不变。

通知 JSON 示例

{
  "app_id": "ak_your_app_id",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792840060",
  "nonce": "本次通知生成的新随机串",
  "sign": "通知签名",
  "notify_id": "BN_example_notification",
  "eventType": "BALANCE_DIVIDE_RESULT",
  "merchantNo": "10000000002",
  "divideRequestId": "DIV_20261024_0001",
  "detailId": "DD_example_detail",
  "detailNo": "DETAIL_EXAMPLE_1",
  "ledgerNo": "10000000003",
  "ledgerType": "MERCHANT",
  "divideAmount": "100.00",
  "feeChargeSide": "OUTSIDE",
  "status": "SUCCESS",
  "reversed": false,
  "version": 1,
  "receiveAmount": "100.00",
  "debitAmount": "100.02",
  "feeAmount": "0.02",
  "finishTime": "2026-10-24 20:00:00",
  "failReason": "",
  "remark": "订单结算",
  "divideReason": "业务分账",
  "occurredAt": 1792840060
}

处理成功返回纯文本 SUCCESS。成功应答规则 ↗ · 重试次数与间隔 ↗

自助结算结果通知 · 按结算申请及结果版本通知

通知采用 POST application/json。请先验签、核对商户及原请求号，使用 notify_id 去重，并按 version 处理通知顺序。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试；同一版本的业务内容不变，timestamp、nonce、sign 可能不同。

接入方收到的参数

参数类型必填 / 位置说明
app_idstring是本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。
sign_typestring是本次通知的签名方式，与该业务申请使用的签名方式一致。 取值：HMAC-SHA256 / RSA2。
timestampstring是本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。
noncestring是本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。
signstring是对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。
notify_idstring是固定通知事件标识，重试不变；请持久化去重。 最大 64 个字符。
eventTypestring是结算结果通知类型。 取值：SETTLEMENT_RESULT。
versioninteger是同一商户、结算请求的单调递增通知版本；仅允许更高版本更新状态。
merchantNostring是原申请商户编号。
settleRequestNostring是原结算业务请求号。
settleOrderNostring是已核实的结算订单号。
settleStatusstring是SUCCESS 结算成功；SETTLE_FAIL 结算异常；RETREATED 已发生打款冲退，不能作为资金仍到账处理。 取值：SUCCESS / SETTLE_FAIL / RETREATED。
settleAmountstring是应结金额，单位元，固定两位小数。
realAmountstring / null是结算到账金额，元；未取得时为 null，不默认等于应结金额。
feeAmountstring / null是结算手续费，元；未知时为 null，明确为零时为 0.00。
retreatFlagboolean / null是true 表示冲退；false 表示本次明确未冲退；null 表示未取得标记。
settleTypestring / null是结算产品；以本次记录为准，未返回时为 null。 最大 64 个字符。
detailListarray / null是全部到账明细，不折叠为其中一条；未取得明细列表时为 null，返回空列表时保持为空。
detailList[].statusstring是到账明细状态：INIT 待处理；REMIT_PROCESS 银行处理中；REMIT_FAIL/ACCOUNTING_FAIL 出款失败；REMIT_SUCCESS/SUCCESS 已到账。 取值：INIT / REMIT_PROCESS / REMIT_FAIL / ACCOUNTING_FAIL / REMIT_SUCCESS / SUCCESS。
detailList[].statusNamestring是该明细状态的中文名称。
detailList[].realAmountstring / null是该明细到账金额，元；未知时为 null，明确为零时为 0.00。
detailList[].accountTypestring / null是目标账户类型：DEBIT_CARD 借记卡、PUBLIC_CARD 对公账户、PASSBOOK 存折、UNIT_SETTLE_CARD 单位结算卡、BANKACCOUNT 银行账户、FEE_ACCOUNT 手续费账户、MARKET_ACCOUNT 营销账户、ACCOUNT 资金账户；未知时为 null。 最大 64 个字符。
detailList[].correctboolean / null是是否打款冲退。true 表示该笔发生冲退，不能仅凭成功状态判断资金仍已到账；null 表示未取得冲退标记。
detailList[].finishTimestring / null是到账完成时间，未返回时为 null；保留查询结果时间文本。 最大 64 个字符。
detailList[].reverseTimestring / null是冲退时间，未返回时为 null。 最大 64 个字符。
occurredAtinteger是本版本结果的确认时间，Unix 秒时间戳；重试时不变。timestamp 为本次通知发送时间。

通知 JSON 示例

{
  "app_id": "ak_example",
  "sign_type": "HMAC-SHA256",
  "timestamp": "1792800000",
  "nonce": "本次投递生成的新随机串",
  "sign": "平台对全部参数生成签名",
  "notify_id": "SN0000000000000000000000000000000000000000",
  "eventType": "SETTLEMENT_RESULT",
  "version": 1,
  "merchantNo": "10000000002",
  "settleRequestNo": "SETTLE_20261024_0001",
  "settleOrderNo": "SETTLE_ORDER_EXAMPLE",
  "settleStatus": "SUCCESS",
  "settleAmount": "100.00",
  "realAmount": null,
  "feeAmount": "0.00",
  "retreatFlag": false,
  "settleType": "D1_MANUAL",
  "detailList": null,
  "occurredAt": 1792800000
}

处理成功返回纯文本 SUCCESS。成功应答规则 ↗ · 重试次数与间隔 ↗

Callback

进件结果回调

进件状态发生变化时，平台向你在 register、update 时登记的 callbackurl 推送结果；成功后的资料变更请先确认查询与通知约定。回调与主动查询互为兜底，两者都应实现。

本节仅说明进件结果，使用 callbackurl 和表单提交。支付、分账和自助结算的 JSON 通知、成功应答及重试次数见「异步通知」；不能将这些规则套用于进件通知。

01

推送方式

以 POST 表单推送到登记地址；当前发送实现可能使用 URL 编码表单或 multipart 表单，请兼容两种表单 Content-Type，不能只按 JSON 接收。

字段类型必填说明
requestNostring是进件请求号，对应 register 返回的 outMchNo，用它关联你方进件申请
applicationStatusstring是当前状态：1 成功 / 2 驳回 / 4 真实性待验证 / 5 待签合同 / 6 业务开通中
auditOpinionstring否审核意见；驳回时为具体原因
merchantNostring否商户号，进件成功后返回
applicationNostring否进件申请单号，可用于核对申请
agreementSignUrlstring否待签合同时的合同签署地址
intentionAuthUrlstring否真实性验证阶段的实名认证地址

通知可能包含扩展字段；请仅依赖本文明确列出的字段处理业务。

02

接收建议

先记录通知，再调用 registerQry 核验并推进关键状态。进件通知尚未单独约定验签及自动重试次数/间隔，请以主动查询兜底，处理成功返回 HTTP 200。

notify.php你的回调端点
$data    = $_POST;                          // 表单提交，不是 JSON body
$outMch  = $data['requestNo'] ?? '';        // 对应进件返回的 outMchNo
$status  = $data['applicationStatus'] ?? '';// 1 成功 / 2 驳回 / 4 / 5 / 6

// 1. 幂等：同一 requestNo + 同一状态只处理一次
// 2. 保存进件状态、审核意见和商户号，供你方业务使用
// 3. 主动查询核验状态；处理成功返回 200，自动重试规则尚未形成承诺

echo 'success';

通知可能重复或乱序到达，请做好去重，并使用 registerQry 核验当前状态；长时间处于处理中或未收到通知时，也可主动查询确认结果。

Security

签名、防重放与结果确认

按约定生成请求签名，使用新的时间戳和随机串，并在应用授权范围内调用接口。业务结果及通知处理要求以各接口说明为准。

双轨签名 HMAC-SHA256 / RSA2

按应用已开通的方式签名。HMAC-SHA256 使用应用密钥；RSA2（SHA256withRSA）使用你方私钥，并须提前登记应用公钥。

防重放 timestamp / nonce

请求时间戳与服务器偏差超过 300 秒即拒绝；nonce 在同一应用下 600 秒内仅可使用一次，重复即判定为重放。

接口授权范围 scope / IP 白名单

请确认应用已获得所需接口权限，调用服务器的出口 IP 须满足应用的 IP 白名单要求。

统一出参 envelope

接口返回 { code, msg, time, data }。请同时检查 HTTP 状态码和 code：1 表示本次处理成功，0 表示失败；msg 为处理提示，time 为秒级时间戳字符串。申请受理不代表业务最终完成。

结果通知 notifyUrl

填写 notifyUrl 接收支付、分账或结算结果。按异步通知说明验签、核对业务信息并处理重复通知；未收到通知时，使用对应查询接口确认。

联调探针 ping

先用 open.ping/index 验证签名链路是否打通，再进入业务接口，避免把签名问题误判为业务问题。

Scope

接入前确认可用能力

  • 当前提供商户进件、聚合支付、支付与资金结果通知、订单与资金查询、订单及余额分账、结算方向配置及自助结算。其他能力以接口条目及应用开通范围为准。
  • 可通过签名通知和订单查询确认交易结果，通过账户及待结算查询了解资金情况，按商户已配置方向发起自助结算，并查询结算和到账结果。订单分账按原订单可用额度分配，余额分账使用资金账户余额；两者均支持结果查询和签名通知。退款、资金账户余额提现及对账文件暂未开放，接入前请确认相关业务处理方案。
  • 商户的经营、订单归属、面向用户的售后退款，由你方系统负责；平台不介入你方与用户之间的交易关系。
  • 接入前建议确认：退款、提现、对账的处理方案是否已具备，以及费率与支付产品范围是否已与平台对齐。

FAQ

常见问题

每个接口都要重复实现一遍签名吗？

不需要。公共客户端负责凭证、时间戳、nonce 和签名；调用时只更换路径与业务参数。先合并全部参数再计算签名，业务参数变化后必须重新签名；无需在每次请求前调用 Ping。

完整请求示例可以直接提交吗？

示例用于说明请求结构。请替换应用凭据、商户号及业务资料；时间戳、nonce 和签名由公共客户端在运行时生成。

channel 是所有接口的公共必填字段吗？

不是。公共参数是 app_id、timestamp、nonce、sign 和可选 sign_type；channel 是部分业务接口的字段。Ping、渠道列表和资料上传不要求 channel。文件上传及各类结果通知的特殊约定见对应条目。

支持哪些商户主体？

支持个体工商户、企业与小微。小微适用于个人经营者；请按主体类型准备商户、证照及结算资料。

小微与企业的进件资料有什么不同？

小微无需提交营业执照相关字段；企业需额外提供营业执照信息、有效期以及结算账户等资料。请按所选主体类型提交，缺少资料时根据返回提示补齐。

签名方式应该选哪个？

按照应用已开通的签名方式接入，默认使用 HMAC-SHA256；使用 RSA2 时先向平台登记应用公钥，并保存平台公钥用于验证通知。

回调地址可以自定义吗？

可以。进件使用 callbackurl；支付、分账和自助结算使用对应请求的 notifyUrl。后者选填，省略或为空时不发送通知。接收参数、成功应答和投递间隔见异步通知；未收到结果时可主动查询。

目前开放哪些支付渠道？

调用 channels 获取当前可用通道，填写接口要求的 channel；支付时使用 payChannel 选择微信或支付宝。

支付与分账能做到什么程度？

商户开通收款能力后，可使用 prePay 发起支付，通过签名通知或 orderQuery 确认结果。选择 DELAY_SETTLE 的订单可在具备条件后调用 orderDivide 分账，用 orderDivideQuery 查询整批结果；资金账户余额可通过 balanceDivide 分账，用 balanceDivideQuery 查询逐笔结果。账户、可结算金额、结算方向、自助结算及结算记录也可通过对应接口查询和处理。退款、资金账户余额提现、完结分账及对账文件暂未开放。

支付结果怎么通知我？

下单时填写 notifyUrl。支付成功后，该地址将收到包含 memo、businessInfo 的签名通知。验签、核对订单与金额并完成幂等处理后返回 SUCCESS；也可调用 orderQuery 查询订单。

自助结算结果如何确认？

selfSettleApply 返回 ACCEPTED 仅表示申请受理。填写 notifyUrl 可接收签名结果通知；省略或为空时，请通过 settleRecordsQuery 查询。通知须验签，按 notify_id 去重并按 version 处理顺序，业务处理成功后返回 SUCCESS。结算成功后发生冲退时，请按更高版本的 RETREATED 通知更新状态。

如何对一笔支付订单继续分账？

下单时选择 DELAY_SETTLE。支付成功后查询 orderQuery，仅在 canDivide=true 且具备可用额度时，使用 orderDivide 按金额分配给同应用商户。单次最多 5 笔，按整批返回成功或失败；填写 notifyUrl 接收签名通知，或用 orderDivideQuery 查询。上一笔结果未确认前，不要提交下一笔；未分配余款继续保留。

余额分账使用哪部分资金，手续费怎么承担？

余额分账从出款商户的资金账户扣款，接收商户须属于同一应用。每笔明细可选择 feeChargeSide=OUTSIDE（出款方额外承担，默认）或 INSIDE（从接收方到账金额中扣除）；实际是否适用取决于已开通的计费方式，实际扣账、到账和手续费以结果为准。申请受理后，使用 balanceDivideQuery 或签名通知确认结果。

一笔余额分账有多个收款商户，通知怎么处理？

结果按明细分别通知。使用 notify_id 去重，并按 detailId 分别保存最新 version，不同明细的版本互不替代。成功后仍可能收到更高版本的失败结果，请更新对应明细；未收到通知时，使用原 divideRequestId 查询，不能换号重复分账。

支持付款码（商家扫用户）吗？

暂未通过开放接口提供。当前只开放主扫（用户扫商户二维码）与 JSAPI 调起两种形态，如有付款码场景需要，请与平台联系确认。

如何开始？

申请接入 → 平台下发 app_id 与密钥 → 用 open.ping/index 验证签名链路 → 提交进件 → 拿到 merchantNo 后即可下单收款。

Get Started

从一次进件，到第一笔收款

申请接入，获取 app_id 与密钥；先用联调探针确认签名链路，提交第一笔进件，商户状态成功后即可下单收款。

申请接入

Contact

客服座机
0371 55571801
客服手机
18137864874