{ "openapi": "3.0.3", "info": { "title": "朝合支付开放平台 API", "version": "2026.10.26", "description": "朝合支付开放平台接入文档。公共参数与业务参数平铺提交，所有调用均需请求签名。请使用公共客户端生成 timestamp、nonce、sign，并替换示例中的应用凭据及业务数据。" }, "servers": [ { "url": "https://你的域名", "description": "替换为实际接入域名。" } ], "paths": { "/api/open.ping/index": { "post": { "operationId": "open_index", "summary": "应用鉴权与原文回显", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "echo": { "type": "string", "description": "按原文签名并原样返回；省略返回空字符串。显式 null、数组、对象、数字或布尔值不接受。", "example": "hello", "default": "" } }, "description": "" } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "echo": "hello", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/IndexResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "验签通过,连接正常", "time": "1792740000", "data": { "app_id": "ak_your_app_id", "app_name": "接入方名称", "pong": true, "echo": "hello" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "使用本接口验证应用凭据与签名。推荐 POST JSON，也支持 POST 表单或 GET；无需 channel，不会发起支付。" ], "errors": [ { "message": "echo 必须为字符串", "when": "将 echo 改为字符串，或者省略该字段。", "http": 200 } ], "responseUnverified": false } }, "get": { "operationId": "open_index_get", "summary": "应用鉴权与原文回显（GET 兼容）", "description": "兼容既有 GET 调用；新接入推荐 POST。查询参数全部参与签名，不需要 channel 或用户 token。", "tags": [ "开放平台" ], "security": [], "parameters": [ { "name": "app_id", "in": "query", "required": true, "schema": { "type": "string", "description": "应用标识；应用须启用并满足本接口 scope 与来源 IP 白名单。", "example": "ak_your_app_id" }, "description": "应用标识；应用须启用并满足本接口 scope 与来源 IP 白名单。" }, { "name": "sign_type", "in": "query", "required": false, "schema": { "type": "string", "description": "本次签名算法；须与应用开通的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ], "default": "HMAC-SHA256" }, "description": "本次签名算法；须与应用开通的签名方式一致。" }, { "name": "timestamp", "in": "query", "required": true, "schema": { "type": "string", "description": "每次请求生成当前秒级时间戳，允许偏差 ±300 秒；兼容毫秒时间戳。", "example": "运行时生成" }, "description": "每次请求生成当前秒级时间戳，允许偏差 ±300 秒；兼容毫秒时间戳。" }, { "name": "nonce", "in": "query", "required": true, "schema": { "type": "string", "description": "每次请求生成新的随机串，同一应用 600 秒内不可重复。", "example": "每次请求生成新随机串" }, "description": "每次请求生成新的随机串，同一应用 600 秒内不可重复。" }, { "name": "sign", "in": "query", "required": true, "schema": { "type": "string", "description": "对全部公共参数、业务参数和 URL 查询参数签名；剔除 sign 自身及空字符串/null。数组转未转义中文和斜杠的 JSON；保留值内的空格与引号。", "example": "由公共客户端计算" }, "description": "对全部公共参数、业务参数和 URL 查询参数签名；剔除 sign 自身及空字符串/null。数组转未转义中文和斜杠的 JSON；保留值内的空格与引号。" }, { "name": "echo", "in": "query", "required": false, "schema": { "type": "string", "description": "按原文签名并原样返回；省略返回空字符串。显式 null、数组、对象、数字或布尔值不接受。", "example": "hello", "default": "" }, "description": "按原文签名并原样返回；省略返回空字符串。显式 null、数组、对象、数字或布尔值不接受。" } ], "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/IndexResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "验签通过,连接正常", "time": "1792740000", "data": { "app_id": "ak_your_app_id", "app_name": "接入方名称", "pong": true, "echo": "hello" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } } } }, "/api/open.merchant/register": { "post": { "operationId": "open_register", "summary": "提交商户进件", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "legal": { "$ref": "#/components/schemas/LegalInfo" }, "business_license": { "$ref": "#/components/schemas/BusinessLicense" }, "settlement": { "$ref": "#/components/schemas/SettlementInfo" }, "channel_extra": { "$ref": "#/components/schemas/ChannelExtra" }, "ubo": { "$ref": "#/components/schemas/UboInfoList" }, "path": { "$ref": "#/components/schemas/MerchantPictures" }, "callbackurl": { "type": "string", "description": "进件结果通知地址，不接收通知时请保留该字段并填写空字符串。", "example": "https://your-domain.com/notify/merchant" }, "parentMerchant": { "type": "string", "description": "上级商户号。", "example": "10000000001" }, "productCodes": { "type": "array", "minItems": 1, "maxItems": 17, "uniqueItems": true, "description": "进件产品代码列表，仅可选择所属应用已配置的产品；省略时使用应用全部产品。每个所选产品均须在 productRates 填写与应用当前配置相等的费用。支付方式与场景须对应所选产品；支付宝 H5_PAY 对应 H5_PAY_M_ALIPAY_OFFLINE。最终开通结果以进件结果为准。", "items": { "type": "string", "enum": [ "MERCHANT_SCAN_WECHAT_OFFLINE", "USER_SCAN_WECHAT_OFFLINE", "WECHAT_OFFIACCOUNT_WECHAT_OFFLINE", "MERCHANT_SCAN_ALIPAY_OFFLINE", "ALIPAY_LIFE_ALIPAY_OFFLINE", "USER_SCAN_ALIPAY_OFFLINE", "MINI_PROGRAM_WECHAT_OFFLINE", "SDK_PAY_WECHAT_OFFLINE", "USER_SCAN_WECHAT_ONLINE", "WECHAT_OFFIACCOUNT_WECHAT_ONLINE", "MINI_PROGRAM_WECHAT_ONLINE", "SDK_PAY_WECHAT_ONLINE", "MINI_PROGRAM_ALIPAY_OFFLINE", "H5_PAY_M_ALIPAY_OFFLINE", "D1_MANUAL", "EASYSHARE_SHARE_MERCHANT", "ENTERPRISE_WITHDRAW_STANDARD_REALTIME" ] }, "example": [ "USER_SCAN_WECHAT_OFFLINE", "D1_MANUAL", "EASYSHARE_SHARE_MERCHANT" ] }, "productRates": { "type": "object", "minProperties": 1, "maxProperties": 17, "description": "所选产品的约定费用，按产品代码索引。每个选中产品必须填写一个十进制字符串，且等于所属应用当前配置，暂不允许加价或减价。不得遗漏所选产品或填写未选产品；百分比按 % 填写，固定费用按元/笔填写，零元也须显式填写。省略 productCodes 时，须填写应用全部产品的费用。", "additionalProperties": { "type": "string", "pattern": "^\\d{1,6}(?:\\.\\d{1,4})?$", "maxLength": 11 }, "example": { "USER_SCAN_WECHAT_OFFLINE": "0.72", "D1_MANUAL": "0.00", "EASYSHARE_SHARE_MERCHANT": "0.02" } } }, "description": "", "required": [ "channel", "merchant", "legal", "settlement", "channel_extra", "path", "callbackurl", "productRates" ] }, { "oneOf": [ { "type": "object", "required": [ "merchant", "business_license" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr", "provinceCode", "cityCode", "districtCode" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "1" ] } } } } }, { "type": "object", "required": [ "merchant", "business_license", "ubo" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr", "provinceCode", "cityCode", "districtCode" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "2" ] } } }, "ubo": { "type": "array", "minItems": 1 } } }, { "type": "object", "required": [ "merchant" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "3" ] } } } } } ] } ] }, "example": { "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" } } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RegisterResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": { "outMchNo": "yibao_example_request" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "提交成功后保存 outMchNo，使用 registerQry 查询进件结果。code=1 表示申请已受理。", "按主体类型提交完整资料：企业、个体提供营业执照资料，小微按对应要求提交身份和门店资料。", "商户资料含特殊符号时，请先联系平台确认填写规范。", "仅可操作或查询当前应用所属的商户和申请记录。", "应用须先配置产品及约定费用；进件时逐项提交相同费用，不能加价或减价。示例费用仅作结构演示，请替换为所属应用各产品的当前配置；配置变化后请重新核对并提交。" ], "errors": [ { "message": "请选择渠道", "when": "提交 channel=yibao。", "http": 200 }, { "message": "申请失败，参数错误：…", "when": "根据提示补齐对应分组字段。", "http": 200 }, { "message": "进件申请失败: …", "when": "先查询并核对原申请状态，再根据返回提示处理。", "http": 200 }, { "message": "请先为应用配置进件产品和约定费用", "when": "由应用管理方先配置可用产品与费用后再提交进件。", "http": 200 }, { "message": "productRates 必须逐项填写所选产品的约定费用，不能缺少或多填", "when": "productRates 的键须与所选产品一一对应；未选产品不要提交。", "http": 200 }, { "message": "productRates 中每个所选产品必须填写十进制费用字符串", "when": "每项费用使用最多四位小数的非负十进制字符串；固定零费用填写 \"0\"。", "http": 200 }, { "message": "…费用必须等于所属应用当前配置 …", "when": "逐项核对当前应用配置，不能加价或减价；应用已调价时重新取得配置后提交。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/mccList": { "post": { "operationId": "open_mccList", "summary": "行业类目查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "level": { "type": "string", "description": "层级：1 一级，2 二级，3 三级。", "example": "1", "enum": [ "1", "2", "3" ], "default": "1" }, "fatherCode": { "type": "string", "description": "父级项 id，取上一级响应的 id/value。", "example": "1" }, "mccCode": { "type": "string", "description": "按字典的 mcc_code 精确筛选。", "example": "5311" } }, "description": "", "required": [ "channel" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "level": "1", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MccListResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": [ { "id": 1, "mcc_name": "零售业", "pid": 0, "level": 1, "mcc_code": 0, "value": 1, "name": "零售业" } ] } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "按层级查询行业目录；进件时使用三级目录项 id。当前不支持 mercType 筛选。" ], "errors": [ { "message": "不支持的渠道", "when": "当前使用 yibao。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/areaCode": { "post": { "operationId": "open_areaCode", "summary": "地区编码查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] } }, "description": "", "required": [ "channel" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AreaCodeResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": [ { "code": "110000", "value": "110000", "name": "北京市", "level": 1 } ] } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "limited", "notes": [ "channel 与公共参数放入 JSON 正文，areaLevel、parentCode 放入 URL；两处参数一起参与签名，可使用公共客户端的第三个 query 参数。", "当前使用 areaLevel、parentCode 查询；不支持按地区名称或批量地区编码筛选。" ], "errors": [ { "message": "不支持的渠道", "when": "正文提交 channel=yibao。", "http": 200 } ], "responseUnverified": false }, "parameters": [ { "name": "areaLevel", "in": "query", "required": false, "description": "当前只读取 URL 查询参数。1 省、2 市、3 区县。", "schema": { "type": "string", "description": "层级。", "enum": [ "1", "2", "3" ] }, "example": "2" }, { "name": "parentCode", "in": "query", "required": false, "description": "父级编码；填写时必须同时提供 areaLevel，查市用 2，查区县用 3。", "schema": { "type": "string", "description": "父级编码。" }, "example": "410000" } ] } }, "/api/open.merchant/bankList": { "post": { "operationId": "open_bankList", "summary": "银行列表查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "bankCode": { "type": "string", "description": "银行编码，精确匹配。", "example": "ABC" } }, "description": "", "required": [ "channel" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "bankCode": "ABC", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BankListResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": [ { "bank_code": "ABC", "value": "ABC", "name": "中国农业银行", "bank_no": "103100000026" } ] } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "返回银行列表；需要名称搜索时，在返回列表中筛选。" ], "errors": [ { "message": "不支持的渠道", "when": "使用 yibao。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/branchList": { "post": { "operationId": "open_branchList", "summary": "支行 / 网点查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "bankCode": { "type": "string", "description": "银行总行编码。", "example": "ABC" }, "provinceCode": { "type": "string", "description": "省编码。", "example": "410000" }, "cityCode": { "type": "string", "description": "市编码。", "example": "410100" }, "branchNo": { "type": "string", "description": "支行联行号，精确匹配。", "example": "103491000018" } }, "description": "", "required": [ "channel" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "bankCode": "ABC", "cityCode": "410100", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BranchListResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": [ { "branch_no": "102100000021", "branch_name": "中国工商银行北京分行营业部", "value": "102100000021-中国工商银行北京分行营业部", "name": "中国工商银行北京分行营业部" } ] } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "可按省市编码、银行编码查询联行号；当前不支持 keyword 名称筛选。" ], "errors": [ { "message": "不支持的渠道", "when": "使用 yibao。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/upload": { "post": { "operationId": "open_upload", "summary": "资料图片上传", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "文件字段固定为 file；文件内容不参与签名。" } }, "description": "", "required": [ "file" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "file": "@/你的本地路径/legal_front.jpg", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UploadResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "上传成功", "time": "1792740000", "data": { "url": "/uploads/20261023/legal_front.jpg" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "使用 multipart/form-data 提交文件，公共参数作为表单字段；文件内容不参与签名。", "上传成功后保存返回的文件地址，用于提交商户资料。" ], "errors": [ { "message": "请上传文件", "when": "确认 multipart 的文件字段名为 file。", "http": 200 }, { "message": "文件上传失败…", "when": "核对文件大小、类型和实际错误提示。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/update": { "post": { "operationId": "open_update", "summary": "驳回后修改进件资料", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "legal": { "$ref": "#/components/schemas/LegalInfo" }, "business_license": { "$ref": "#/components/schemas/BusinessLicense" }, "settlement": { "$ref": "#/components/schemas/SettlementInfo" }, "channel_extra": { "$ref": "#/components/schemas/ChannelExtra" }, "ubo": { "type": "array", "items": { "type": "object", "properties": { "uboName": { "type": "string", "description": "受益人姓名。", "example": "张三" }, "uboIdCard": { "type": "string", "description": "受益人身份证号。", "example": "410000199001011234" }, "uboIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "uboIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" }, "uboPhone": { "type": "string", "description": "受益人电话。", "example": "13800138000" }, "uboAddress": { "type": "string", "description": "受益人证件/联系地址。", "example": "河南省郑州市中原区某某街道 100 号" }, "uboFrontPicLocal": { "type": "string", "description": "身份证正面文件路径，取 upload 返回的 data.url。", "example": "/uploads/20261023/uboFront.jpg" }, "uboBackPicLocal": { "type": "string", "description": "身份证反面文件路径，取 upload 返回的 data.url。", "example": "/uploads/20261023/uboBack.jpg" } }, "description": "", "required": [ "uboName", "uboIdCard", "uboIdStartDate", "uboIdEndDate", "uboFrontPicLocal", "uboBackPicLocal" ] }, "description": "受益人资料。企业需按进件资料要求提供，小微可传空数组。", "x-required-label": "是，可为空数组" }, "path": { "$ref": "#/components/schemas/MerchantPictures" }, "callbackurl": { "type": "string", "description": "进件结果通知地址，不接收通知时请保留该字段并填写空字符串。", "example": "https://your-domain.com/notify/merchant" }, "parentMerchant": { "type": "string", "description": "上级商户号。", "example": "10000000001" }, "outMchNo": { "type": "string", "description": "register 返回的进件请求号。", "example": "yibao_example_request" } }, "description": "", "required": [ "channel", "merchant", "legal", "settlement", "channel_extra", "path", "callbackurl", "outMchNo", "ubo" ] }, { "oneOf": [ { "type": "object", "required": [ "merchant", "business_license" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr", "provinceCode", "cityCode", "districtCode" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "1" ] } } } } }, { "type": "object", "required": [ "merchant", "business_license", "ubo" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr", "provinceCode", "cityCode", "districtCode" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "2" ] } } }, "ubo": { "type": "array", "minItems": 1 } } }, { "type": "object", "required": [ "merchant" ], "properties": { "merchant": { "type": "object", "required": [ "etpsAttr" ], "properties": { "etpsAttr": { "type": "string", "enum": [ "3" ] } } } } } ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": "成功" } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "用于修改已驳回的进件申请。请提交完整资料，审核中及待签约状态不支持修改。", "callbackurl 不接收通知时填写空字符串；ubo 没有资料时保留为空数组。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [ { "message": "进件信息不存在", "when": "核对 outMchNo。", "http": 200 }, { "message": "该状态进件信息不能修改！", "when": "确认原申请已驳回。", "http": 200 }, { "message": "申请失败，参数错误：…", "when": "补齐完整进件资料。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/modifyMerchant": { "post": { "operationId": "open_modifyMerchant", "summary": "成功后变更商户资料", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "legal": { "$ref": "#/components/schemas/LegalInfo" }, "business_license": { "$ref": "#/components/schemas/BusinessLicense" }, "settlement": { "$ref": "#/components/schemas/SettlementInfo" }, "channel_extra": { "$ref": "#/components/schemas/ChannelExtra" }, "ubo": { "$ref": "#/components/schemas/UboInfoList" }, "path": { "$ref": "#/components/schemas/MerchantPictures" }, "outMchNo": { "type": "string", "description": "已进件成功的商户请求号。", "example": "yibao_example_request" } }, "description": "", "required": [ "channel", "outMchNo", "merchant", "legal", "settlement", "channel_extra", "path", "ubo" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ModifyMerchantResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": { "applicationNo": "渠道变更申请单号", "applicationStatus": "渠道状态值" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "limited", "notes": [ "商户进件成功后方可变更资料。提交完整资料，ubo、path 无数据时也应保留字段。", "资料变更需先联系平台确认可用申请信息；获得 requestNo 后使用 modifyQry 查询进度。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [ { "message": "当前商户未进件成功无法申请商户资料变更", "when": "先查询原进件状态。", "http": 200 }, { "message": "修改失败: …", "when": "核对提交资料及返回提示。", "http": 200 } ], "responseUnverified": true } } }, "/api/open.merchant/modifyQry": { "post": { "operationId": "open_modifyQry", "summary": "资料变更进度查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "requestNo": { "type": "string", "description": "变更请求号，不是原进件 outMchNo。须先与平台确认该号码的获取方式。", "example": "YIBAO_MODIFY_example" } }, "description": "", "required": [ "channel", "requestNo" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "requestNo": "YIBAO_MODIFY_example", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ModifyQryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": {} } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "limited", "notes": [ "使用资料变更时取得的 requestNo 查询，不能使用原进件 outMchNo。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [], "responseUnverified": true } } }, "/api/open.merchant/registerQry": { "post": { "operationId": "open_registerQry", "summary": "进件进度查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "requestNo": { "type": "string", "description": "register 返回的 outMchNo；此接口的入参字段名叫 requestNo。", "example": "yibao_example_request" } }, "description": "", "required": [ "channel", "requestNo" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "requestNo": "yibao_example_request", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RegisterQryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": { "applicationStatus": 1, "auditOpinion": "", "requestNo": "yibao_example_request", "merchantNo": "10093518558", "elecSignUrl": "", "intentionAuthUrl": "" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "使用进件申请返回的 outMchNo 作为 requestNo 查询进度。", "申请尚未完成时，主要返回 applicationStatus、auditOpinion、requestNo；成功后可取得用于收款的 merchantNo。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [ { "message": "入网请求号不能为空", "when": "提供 requestNo。", "http": 200 }, { "message": "您未发起该请求号对应的入网申请,请核实", "when": "核对原进件返回的 outMchNo。", "http": 200 } ], "responseUnverified": false } } }, "/api/open.merchant/merchantStatusQry": { "post": { "operationId": "open_merchantStatusQry", "summary": "渠道商户状态查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "mchNo": { "type": "string", "description": "商户号，对应 registerQry 返回的 merchantNo。", "example": "10093518558" } }, "description": "", "required": [ "channel", "mchNo" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "mchNo": "10093518558", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MerchantStatusQryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": {} } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "blocked", "notes": [ "此接口暂未开放正式接入。查询进件结果请使用 registerQry。" ], "errors": [ { "message": "商户号不能为空", "when": "提供 mchNo。", "http": 200 }, { "message": "响应不是有效 JSON", "when": "此接口暂未开放，请使用 registerQry 查询进件结果。", "http": 200 } ], "responseUnverified": true } } }, "/api/open.merchant/channels": { "post": { "operationId": "open_channels", "summary": "可用渠道列表", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": {}, "description": "" } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChannelsResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "success", "time": "1792740000", "data": { "yibao": "易宝" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "查询当前可用的收款通道标识；无需业务参数，按公共协议签名调用。" ], "errors": [], "responseUnverified": false } } }, "/api/open.merchant/wechatAuthApply": { "post": { "operationId": "open_wechatAuthApply", "summary": "微信实名认证申请", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "mchNo": { "type": "string", "description": "商户号。", "example": "10093518558" }, "id": { "type": "integer", "description": "商户记录标识，调用前联系平台获取并确认。", "example": 123 }, "etpsAttr": { "type": "string", "description": "主体类型。", "example": "2", "enum": [ "1", "2", "3" ] }, "artifPhone": { "type": "string", "description": "法人手机号。", "example": "13800138000" }, "certifIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "certifIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" }, "provinceName": { "type": "string", "description": "省名称。", "example": "河南省" }, "cityName": { "type": "string", "description": "市名称。", "example": "郑州市" }, "districtName": { "type": "string", "description": "区县名称。", "example": "中原区" }, "addressReg": { "type": "string", "description": "详细地址。", "example": "某某街道 100 号 3 层" }, "businessLicenseStartDate": { "type": "string", "description": "执照开始日期。", "example": "2019-06-01" }, "businessLicenseEndDate": { "type": "string", "description": "执照结束日期或“长期”。", "example": "2039-06-01" }, "pics": { "type": "object", "properties": { "03": { "type": "string", "description": "证照资源标识；请在调用前确认所需资源标识，不可使用 upload 返回的文件路径代替。", "example": "渠道证照资源标识" }, "05": { "type": "string", "description": "小微门头照片的渠道资源标识。", "example": "渠道门头资源标识", "x-required-label": "小微条件" }, "04": { "type": "string", "description": "小微店内照片的渠道资源标识。", "example": "渠道店内资源标识", "x-required-label": "小微条件" } }, "description": "", "required": [ "03" ] }, "mchName": { "type": "string", "description": "小微门店名。", "example": "某某门店", "x-required-label": "小微条件" }, "busCityCode": { "type": "string", "description": "小微经营地址市编码。", "example": "410100", "x-required-label": "小微条件" } }, "description": "", "required": [ "channel", "mchNo", "id", "etpsAttr", "artifPhone", "certifIdStartDate", "certifIdEndDate", "provinceName", "cityName", "districtName", "addressReg", "businessLicenseStartDate", "businessLicenseEndDate", "pics" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WechatAuthApplyResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": { "applymentId": "渠道申请单号" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "limited", "notes": [ "此功能需平台协助开通。调用前请联系平台确认商户 id、图片资源标识及所需商户资料。", "按本接口要求平铺提交字段，不使用 register 的嵌套分组；pics 使用已确认的资源标识。", "保存申请返回的 applymentId，作为后续认证查询的 applyNo。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [], "responseUnverified": true } } }, "/api/open.merchant/alipayAuthApply": { "post": { "operationId": "open_alipayAuthApply", "summary": "支付宝实名认证申请", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "mchNo": { "type": "string", "description": "商户号。", "example": "10093518558" }, "id": { "type": "integer", "description": "商户记录标识，调用前联系平台获取并确认。", "example": 123 }, "etpsAttr": { "type": "string", "description": "主体类型。", "example": "2", "enum": [ "1", "2", "3" ] }, "artifPhone": { "type": "string", "description": "法人手机号。", "example": "13800138000" }, "certifIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "certifIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" }, "provinceName": { "type": "string", "description": "省名称。", "example": "河南省" }, "cityName": { "type": "string", "description": "市名称。", "example": "郑州市" }, "districtName": { "type": "string", "description": "区县名称。", "example": "中原区" }, "addressReg": { "type": "string", "description": "详细地址。", "example": "某某街道 100 号 3 层" }, "businessLicenseStartDate": { "type": "string", "description": "执照开始日期。", "example": "2019-06-01" }, "businessLicenseEndDate": { "type": "string", "description": "执照结束日期或“长期”。", "example": "2039-06-01" }, "pics": { "type": "object", "properties": { "05": { "type": "string", "description": "小微门头照片的渠道资源标识。", "example": "渠道门头资源标识", "x-required-label": "小微条件" }, "04": { "type": "string", "description": "小微店内照片的渠道资源标识。", "example": "渠道店内资源标识", "x-required-label": "小微条件" } }, "description": "", "required": [ "04", "05" ], "x-required-label": "小微条件" }, "mchName": { "type": "string", "description": "小微门店名。", "example": "某某门店", "x-required-label": "小微条件" }, "busCityCode": { "type": "string", "description": "小微经营地址市编码。", "example": "410100", "x-required-label": "小微条件" }, "artifCertifType": { "type": "string", "description": "法人证件类型。", "example": "00" }, "businessLicense": { "type": "string", "description": "营业执照编号。", "example": "91410100MA3XXXXXXX" }, "uboInfoList": { "type": "array", "items": { "type": "object", "properties": { "uboName": { "type": "string", "description": "受益人姓名。", "example": "张三" }, "uboIdCard": { "type": "string", "description": "受益人证件号。", "example": "410000199001011234" }, "uboFrontPic": { "type": "string", "description": "正面渠道图片标识。", "example": "渠道受益人正面资源" }, "uboBackPic": { "type": "string", "description": "反面渠道图片标识。", "example": "渠道受益人反面资源" }, "uboAddress": { "type": "string", "description": "受益人地址。", "example": "河南省郑州市中原区某某街道" }, "uboIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "uboIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" } }, "description": "", "required": [ "uboName", "uboIdCard", "uboFrontPic", "uboBackPic", "uboAddress", "uboIdStartDate", "uboIdEndDate" ] }, "description": "此申请使用 uboInfoList，不是 register 的 ubo；图片使用渠道资源标识。" }, "busProvinceCode": { "type": "string", "description": "小微经营省编码。", "example": "410000", "x-required-label": "小微条件" }, "busDistrictCode": { "type": "string", "description": "小微经营区县编码。", "example": "410102", "x-required-label": "小微条件" }, "addressBuss": { "type": "string", "description": "小微经营详细地址。", "example": "某某街道 100 号 3 层", "x-required-label": "小微条件" } }, "description": "", "required": [ "channel", "mchNo", "id", "etpsAttr", "artifPhone", "certifIdStartDate", "certifIdEndDate", "provinceName", "cityName", "districtName", "addressReg", "businessLicenseStartDate", "businessLicenseEndDate", "artifCertifType", "businessLicense", "uboInfoList" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AlipayAuthApplyResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": { "applymentId": "渠道申请单号" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "limited", "notes": [ "此功能需平台协助开通。调用前请联系平台确认商户 id、图片资源标识及所需商户资料。", "按本接口要求平铺提交字段，不使用 register 的嵌套分组；pics 使用已确认的资源标识。", "保存申请返回的 applymentId，作为后续认证查询的 applyNo。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [], "responseUnverified": true } } }, "/api/open.merchant/wechatAuthQry": { "post": { "operationId": "open_wechatAuthQry", "summary": "微信实名认证状态查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "applyNo": { "type": "string", "description": "申请受理结果中的 applymentId；本接口入参名为 applyNo。", "example": "渠道申请单号" }, "mchNo": { "type": "string", "description": "商户号。", "example": "10093518558" } }, "description": "", "required": [ "channel", "applyNo", "mchNo" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "applyNo": "渠道申请单号", "mchNo": "10093518558", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WechatAuthQryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": {} } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "使用认证申请返回的申请单号查询认证结果。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [], "responseUnverified": true } } }, "/api/open.merchant/alipayAuthQry": { "post": { "operationId": "open_alipayAuthQry", "summary": "支付宝实名认证状态查询", "description": "公共协议见“公共参数与签名”。本接口的业务字段、完整请求和业务响应定义如下。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "开放平台文档约定的渠道。", "example": "yibao", "enum": [ "yibao" ] }, "applyNo": { "type": "string", "description": "申请受理结果中的 applymentId；本接口入参名为 applyNo。", "example": "渠道申请单号" }, "mchNo": { "type": "string", "description": "商户号。", "example": "10093518558" } }, "description": "", "required": [ "channel", "applyNo", "mchNo" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "applyNo": "渠道申请单号", "mchNo": "10093518558", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AlipayAuthQryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "操作成功", "time": "1792740000", "data": {} } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "使用认证申请返回的申请单号查询认证结果。", "仅可操作或查询当前应用所属的商户和申请记录。" ], "errors": [], "responseUnverified": true } } }, "/api/open.merchant/prePay": { "post": { "operationId": "open_prePay", "summary": "聚合支付下单", "description": "为已开通收款能力的商户创建支付订单。按支付方式获取二维码内容、H5 支付链接或支付调起参数，完成支付后通过结果通知或订单查询确认支付状态。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "收款通道标识，当前固定填写 yibao。", "example": "yibao", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "收款商户号，可从商户进件结果获取；须已开通对应支付能力。", "example": "10000000002" }, "orderAmount": { "type": "string", "description": "订单金额，单位元，范围 0.01 至 99999999.99，最多两位小数。", "example": "100.00", "pattern": "^(?:0\\.(?:0[1-9]|[1-9][0-9]?)|[1-9][0-9]{0,7}(?:\\.[0-9]{1,2})?)$" }, "payWay": { "type": "string", "description": "支付方式须与 payChannel 组合选择：WECHAT 支持 USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY；ALIPAY 支持 USER_SCAN / MINI_PROGRAM / ALIPAY_LIFE / H5_PAY。", "example": "USER_SCAN", "enum": [ "USER_SCAN", "WECHAT_OFFIACCOUNT", "MINI_PROGRAM", "SDK_PAY", "ALIPAY_LIFE", "H5_PAY" ] }, "goodsName": { "type": "string", "description": "商品名称，必填。", "example": "测试商品", "maxLength": 85 }, "userId": { "type": "string", "description": "付款人标识：微信公众号或小程序填写 openId，支付宝生活号或小程序填写支付宝 userId，须与 appId 对应。扫码、微信 SDK 和 H5 支付可不传。", "example": "付款人标识", "x-required-label": "公众号 / 小程序 / 生活号必填", "maxLength": 128 }, "appId": { "type": "string", "description": "支付应用 ID；公众号、小程序、生活号和微信 SDK 支付必传，须对应已开通的支付应用。与公共参数 app_id 区分填写。", "example": "你的支付应用ID", "x-required-label": "公众号 / 小程序 / 生活号 / SDK 必填", "maxLength": 64 }, "orderId": { "type": "string", "description": "商户业务订单号，建议必传且全局唯一。由 1 至 64 位字母、数字、下划线或连字符组成；不传则自动生成。相同订单重试须保持业务参数一致。", "example": "SH20261023000001", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "scene": { "type": "string", "description": "支付场景：ONLINE 线上，OFFLINE 线下。微信支持两种场景，支付宝仅支持 OFFLINE；须已开通对应场景的支付产品。", "example": "OFFLINE", "enum": [ "ONLINE", "OFFLINE" ], "default": "OFFLINE" }, "userIp": { "type": "string", "description": "付款人 IP 地址，可不传。", "example": "192.0.2.1" }, "payChannel": { "type": "string", "enum": [ "WECHAT", "ALIPAY" ], "description": "支付渠道：WECHAT 微信，ALIPAY 支付宝。建议显式填写；省略时 ALIPAY_LIFE、H5_PAY 默认 ALIPAY，其余默认 WECHAT。小程序支付请按实际渠道填写。与固定为 yibao 的 channel 区分。", "example": "WECHAT" }, "expiredTime": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$", "description": "支付截止时间，使用北京时间 yyyy-MM-dd HH:mm:ss，须晚于当前时间。省略时默认 30 分钟有效；同单重试保持原值。", "example": "2026-10-23 23:00:00" }, "fundProcessType": { "type": "string", "enum": [ "REAL_TIME", "DELAY_SETTLE" ], "default": "REAL_TIME", "description": "资金处理方式。REAL_TIME：支付成功后自动处理费用并释放商户余款。DELAY_SETTLE：保留商户余款待后续处理；后续可按订单分账接口处理，完结分账暂未开放。", "example": "REAL_TIME" }, "notifyUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "支付成功通知地址，建议填写可从公网访问的 HTTP(S) 地址，使用标准端口，不能包含用户名或 URL 片段。不传则不发送支付通知。", "example": "https://merchant.example.com/payment/notify" }, "memo": { "type": "string", "maxLength": 256, "description": "业务备注，在支付通知和订单查询中原样返回。", "example": "外部订单备注 A&B" }, "businessInfo": { "type": "string", "maxLength": 4096, "x-max-bytes": 4096, "description": "业务扩展信息，填写 JSON 对象或数组字符串，最多 4096 个 UTF-8 字节；在支付通知和订单查询中原样返回。", "example": "{\"externalOrderId\":\"EXT202610230001\",\"source\":\"open-api\"}" } }, "description": "", "required": [ "channel", "merchantNo", "orderAmount", "payWay", "goodsName" ], "not": { "required": [ "divideDetail" ] }, "allOf": [ { "oneOf": [ { "properties": { "payWay": { "enum": [ "USER_SCAN", "H5_PAY" ] } } }, { "properties": { "payWay": { "enum": [ "WECHAT_OFFIACCOUNT", "MINI_PROGRAM", "ALIPAY_LIFE" ] }, "appId": { "type": "string", "minLength": 1, "pattern": "\\S" }, "userId": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "required": [ "appId", "userId" ] }, { "properties": { "payWay": { "enum": [ "SDK_PAY" ] }, "appId": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "required": [ "appId" ] } ] }, { "anyOf": [ { "properties": { "payWay": { "enum": [ "USER_SCAN", "WECHAT_OFFIACCOUNT", "MINI_PROGRAM", "SDK_PAY" ] }, "payChannel": { "enum": [ "WECHAT" ] }, "scene": { "enum": [ "ONLINE", "OFFLINE" ] } } }, { "properties": { "payWay": { "enum": [ "USER_SCAN", "MINI_PROGRAM", "ALIPAY_LIFE", "H5_PAY" ] }, "payChannel": { "enum": [ "ALIPAY" ] }, "scene": { "enum": [ "OFFLINE" ] } }, "required": [ "payChannel" ] }, { "properties": { "payWay": { "enum": [ "ALIPAY_LIFE", "H5_PAY" ] }, "payChannel": { "enum": [ "ALIPAY" ] }, "scene": { "enum": [ "OFFLINE" ] } } } ] } ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PrePayResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "notes": [ "应用与收款商户须已开通所选支付方式及场景的产品。channel 固定填写 yibao；下表中的微信或支付宝选择使用 payChannel 参数。", "code=1 表示下单成功，不表示付款完成。请以已验签的支付结果通知或 orderQuery 查询结果确认支付状态。", "每笔业务使用唯一 orderId。请求超时或结果不确定时，先查询原订单；同单重试保持业务参数一致。", "通知成功应答为 HTTP 2xx 与纯文本 SUCCESS；同一通知最多自动投递 10 次（含首次），失败等待间隔为 10、20、40、80、160、320、640、1280、2560 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。" ], "errors": [ { "message": "payChannel 与 payWay 组合不支持", "when": "按文档支持的微信/支付宝组合提交。", "http": 200 }, { "message": "订单金额须为 0.01 至 99999999.99 元，最多两位小数", "when": "用十进制元金额提交，勿传超精度或科学计数法字符串。", "http": 200 }, { "message": "goodsName 必须为非空字符串且不超过 85 个字符", "when": "明确提供商品名称。", "http": 200 }, { "message": "orderId 已存在且请求归属或业务参数不一致", "when": "勿跨应用复用订单号或修改同一订单业务参数。", "http": 200 }, { "message": "expiredTime 必须晚于当前时间", "when": "按北京时间设置未来截止时间。", "http": 200 }, { "message": "应用未启用该支付产品", "when": "联系平台确认当前应用已开通所选支付产品。", "http": 200 }, { "message": "scene 仅支持 ONLINE、OFFLINE", "when": "按支持的场景取值提交；省略时默认 OFFLINE。", "http": 200 }, { "message": "支付宝支付当前仅支持 scene=OFFLINE", "when": "payChannel=ALIPAY 时使用 OFFLINE。", "http": 200 }, { "message": "公众号、小程序、生活号支付必须明确提供 appId 和 userId", "when": "按所选支付方式提交非空的支付应用 ID 和付款人标识。", "http": 200 }, { "message": "微信 SDK 支付必须明确提供 appId", "when": "SDK_PAY 必须填写支付应用 appId；userId 可省略。", "http": 200 } ], "responseUnverified": false, "paymentCombinations": [ [ "WECHAT", "ONLINE / OFFLINE", "USER_SCAN / WECHAT_OFFIACCOUNT / MINI_PROGRAM / SDK_PAY" ], [ "ALIPAY", "OFFLINE", "USER_SCAN / MINI_PROGRAM / ALIPAY_LIFE / H5_PAY" ] ] }, "callbacks": { "paymentResult": { "{$request.body#/notifyUrl}": { "post": { "summary": "支付成功通知", "description": "支付成功后，下单时填写的 notifyUrl 将收到 POST JSON 通知。通知签名方式与下单请求一致；HMAC-SHA256 使用应用密钥验签，RSA2 使用平台提供的通知公钥验签。重复通知使用同一 notify_id，请在业务处理成功后返回 SUCCESS。", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResultNotification" }, "example": { "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": "平台使用应用凭证生成的通知签名" } } } }, "responses": { "200": { "description": "业务可靠处理后返回 HTTP 2xx 与纯文本 SUCCESS，忽略大小写和首尾空白；确认后结束当前 notify_id 的自动投递。其他响应、网络错误或超时按统一规则重试，同一通知最多自动投递 10 次（含首次）；无暂停响应指令。", "content": { "text/plain": { "schema": { "type": "string" }, "example": "SUCCESS" } } } }, "x-notification-policy": { "$ref": "#/x-notification-policy" } } } } } } }, "/api/open.merchant/balanceDivide": { "post": { "operationId": "open_balanceDivide", "summary": "余额分账申请", "description": "使用当前应用商户的资金账户，向同一应用下的商户账户申请分账。手续费承担方式可逐笔选择。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "收款通道标识，固定填写 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "出款商户号，须属于当前签名应用且已完成入网并开通分账能力。", "maxLength": 16 }, "divideRequestId": { "type": "string", "description": "你方生成的业务请求号，同一出款商户内唯一。结果不明确时保持原号查询，不能换号重试。", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "divideDetail": { "type": "string", "description": "JSON 数组字符串，原文及规范编码后均不超过 1024 个 UTF-8 字节，包含 1 至 30 笔明细；各笔字段见下表。", "maxLength": 1024, "x-json-schema": { "$ref": "#/components/schemas/BalanceDivideRequestDetails" } }, "notifyUrl": { "type": "string", "description": "接收逐笔分账结果通知的公网 HTTP(S) 地址。省略或为空字符串时不发送通知，请使用 balanceDivideQuery 查询。", "maxLength": 2048 } }, "required": [ "channel", "merchantNo", "divideRequestId", "divideDetail" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BalanceDivideResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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" } ] } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "服务暂不可用，本次请求未受理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "出款商户与全部接收商户均须属于当前应用，且已满足相应分账产品和商户关系要求。接口权限标识为 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 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。" ], "errors": [ { "message": "余额分账暂未开放", "http": 200, "when": "请确认应用和商户已获得余额分账接入权限。" }, { "message": "商户不存在或无权访问", "http": 200, "when": "核对出款商户及每一笔接收商户，均须属于当前应用。" }, { "message": "divideDetail 必须为不超过 1024 字节的有效 JSON 数组字符串", "http": 200, "when": "使用 JSON 数组字符串，不要传对象、直接数组或 HTML 转义后的字符串。" }, { "message": "分账明细编码后不得超过 1024 字节", "http": 200, "when": "减少单次明细数量或附言长度；每次最多 30 笔，同时满足长度限制。" }, { "message": "分账接收方不可重复", "http": 200, "when": "同一次申请中每个接收商户仅可出现一次。" }, { "message": "feeChargeSide 仅支持 OUTSIDE、INSIDE", "http": 200, "when": "在每笔明细内填写有效的承担方式。" }, { "message": "divideRequestId 已存在且归属或业务参数不一致", "http": 200, "when": "查询并核对原申请，勿修改参数或换应用重提。" }, { "message": "分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试", "http": 200, "when": "原申请可能已受理，继续使用原请求号核对结果。" }, { "message": "余额分账不支持参数 <字段>", "http": 200, "when": "按参数表提交请求，删除未开放字段；结果通知地址使用 notifyUrl。" } ] }, "callbacks": { "balanceDivideResult": { "{$request.body#/notifyUrl}": { "post": { "summary": "逐笔余额分账结果通知", "description": "通知采用 POST application/json，签名方式与申请一致。HMAC-SHA256 使用应用密钥验签；RSA2 使用通知公钥验签。核对商户、请求号、明细和金额，按 notify_id 去重、按 detailId 分别比较 version。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试，同一版本的业务内容不变。", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceDivideResultNotification" }, "example": { "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 } } } }, "responses": { "200": { "description": "业务可靠处理后返回 HTTP 2xx 与纯文本 SUCCESS，忽略大小写和首尾空白；确认后结束当前 notify_id 的自动投递。其他响应、网络错误或超时按统一规则重试，同一通知最多自动投递 10 次（含首次）；无暂停响应指令。", "content": { "text/plain": { "schema": { "type": "string" }, "example": "SUCCESS" } } } }, "x-notification-policy": { "$ref": "#/x-notification-policy" } } } } } } }, "/api/open.merchant/balanceDivideQuery": { "post": { "operationId": "open_balanceDivideQuery", "summary": "余额分账结果查询", "description": "按原出款商户号和分账请求号，查询本应用申请的逐笔余额分账结果、实际金额和手续费。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "收款通道标识，固定填写 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "出款商户号，须属于当前签名应用且已完成入网并开通分账能力。", "maxLength": 16 }, "divideRequestId": { "type": "string", "description": "你方生成的业务请求号，同一出款商户内唯一。结果不明确时保持原号查询，不能换号重试。", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "channel", "merchantNo", "divideRequestId" ] } ] }, "example": { "app_id": "ak_your_app_id", "sign_type": "HMAC-SHA256", "timestamp": "运行时生成", "nonce": "每次请求生成新随机串", "channel": "yibao", "merchantNo": "10000000002", "divideRequestId": "DIV_20261024_0001", "sign": "由公共客户端计算" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BalanceDivideQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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" } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "服务暂不可用，本次请求未受理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可查询本应用发起的申请；查询权限标识为 open.merchant/balancedividequery，申请权限与查询权限分别授权。", "使用原 merchantNo 和 divideRequestId 查询；不能用支付订单号、结算请求号替代。", "请完整处理 detailList。不同明细可有不同结果；PROCESSING 表示尚有明细待确认，PARTIAL_SUCCESS 表示全部处理后部分成功。", "成功结果后续仍可能变为 FAIL，请结合较高版本通知及查询结果处理冲退。", "所有金额以元为单位，返回两位小数字符串。null 表示未取得有效金额，不得按零或申请金额处理；任一明细金额未知时，对应汇总金额为 null。", "queriedAt 是最后一次成功核对结果的 Unix 秒时间戳。查询结果可能短暂延迟，建议轮询间隔不短于 5 秒。", "查询失败、受理结果不明或暂未查到申请，均不能作为换号重新分账的依据。", "商户关联至其他应用后，历史申请仍仅限原发起应用查询。" ], "errors": [ { "message": "分账申请不存在或无权访问", "http": 200, "when": "核对原商户号、分账请求号及发起应用。" }, { "message": "余额分账查询暂不可用，请稍后使用原请求号查询或联系技术支持", "http": 200, "when": "继续用原请求号核对，勿换号再次申请。" } ] } } }, "/api/open.merchant/orderDivide": { "post": { "operationId": "open_orderDivide", "summary": "订单分账申请", "description": "将原订单的可分账金额，按指定金额分配至同一应用下的商户。", "tags": [ "支付" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "渠道标识，固定填写 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "原订单的收款商户编号，须属于当前应用。", "maxLength": 11 }, "orderId": { "type": "string", "description": "原支付订单号，须为当前应用创建的订单。", "maxLength": 64 }, "divideRequestId": { "type": "string", "description": "你方生成的分账请求号，同一收款商户内唯一。", "maxLength": 64, "pattern": "^[A-Za-z0-9_]+$" }, "divideDetail": { "type": "string", "description": "按金额分账的 JSON 数组字符串，长度限制为 1000 个 UTF-8 字节；各笔字段见下表。", "maxLength": 1000, "x-max-bytes": 1000, "x-json-schema": { "$ref": "#/components/schemas/OrderDivideRequestDetails" } }, "notifyUrl": { "type": "string", "description": "接收本批订单分账结果签名通知的公网 HTTP(S) 地址。选填；省略或为空字符串时不发送通知。", "maxLength": 2048 } }, "required": [ "channel", "merchantNo", "orderId", "divideRequestId", "divideDetail" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "业务响应；实际处理状态见 data.status。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDivideApplyResponse" }, "example": { "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 } } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅支持已支付且当前可分账的 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 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。" ], "errors": [ { "message": "订单暂不可分账，请稍后查询", "http": 200, "when": "先查询原订单的 canDivide，确认业务条件后再提交。" }, { "message": "该订单存在未确认的分账申请，请先查询原申请", "http": 200, "when": "使用上一笔 divideRequestId 查询，不能更换请求号重复申请。" }, { "message": "分账总金额超过订单可用额度 / 分账总金额超过订单剩余可分账金额", "http": 200, "when": "核对 availableDivideAmount，减少本次申请金额。" }, { "message": "分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试", "http": 200, "when": "继续查询原申请；未查到不能认定原申请未受理。" }, { "message": "订单分账不支持参数 <字段>", "http": 200, "when": "按参数表提交，删除比例、发起方、解冻余款及其他未开放字段。" }, { "message": "商户不存在或无权访问", "http": 200, "when": "核对订单、出款商户及全部接收商户的应用归属。" }, { "message": "divideRequestId 已存在且归属或业务参数不一致", "http": 200, "when": "核对原申请，不能更改订单、金额、接收方、通知地址或应用重复提交。" }, { "message": "请稍后发起订单分账，勿频繁调用", "http": 200, "when": "支付成功后稍等，且同一订单分账申请至少间隔 3 秒。" } ] }, "callbacks": { "orderDivideResult": { "{$request.body#/notifyUrl}": { "post": { "summary": "订单分账结果通知", "description": "每次申请按整批发送最终结果。通知签名方式与原申请一致：HMAC-SHA256 使用应用密钥验签，RSA2 使用通知公钥验签。收到较低版本或重复通知时，不重复记账。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDivideNotification" }, "example": { "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": "由实际通知参数计算" } } } }, "responses": { "200": { "description": "业务可靠处理后返回 HTTP 2xx 与纯文本 SUCCESS，忽略大小写和首尾空白；确认后结束当前 notify_id 的自动投递。其他响应、网络错误或超时按统一规则重试，同一通知最多自动投递 10 次（含首次）；无暂停响应指令。", "content": { "text/plain": { "schema": { "type": "string" }, "example": "SUCCESS" } } } }, "x-notification-policy": { "$ref": "#/x-notification-policy" } } } } } } }, "/api/open.merchant/orderDivideQuery": { "post": { "operationId": "open_orderDivideQuery", "summary": "订单分账结果查询", "description": "按原订单号及分账请求号查询整批处理结果、明细和实际分账费用。", "tags": [ "支付" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "channel": { "type": "string", "description": "渠道标识，固定填写 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "原订单的收款商户编号，须属于当前应用。", "maxLength": 11 }, "orderId": { "type": "string", "description": "原支付订单号，须为当前应用创建的订单。", "maxLength": 64 }, "divideRequestId": { "type": "string", "description": "你方生成的分账请求号，同一收款商户内唯一。", "maxLength": 64, "pattern": "^[A-Za-z0-9_]+$" } }, "required": [ "channel", "merchantNo", "orderId", "divideRequestId" ] } ] }, "example": { "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": "由公共客户端计算" } } } }, "responses": { "200": { "description": "业务响应；实际处理状态见 data.status。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDivideQueryResponse" }, "example": { "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": "供应商结算" } ] } } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "只可查询原发起应用的分账申请；商户后续改绑不转移历史记录归属。", "查询原申请不会再次发起分账。结果为 UNKNOWN 或 PROCESSING 时继续查询；请勿换请求号重复申请。", "feeAmount、receiveAmount 为已确认的实际金额，null 表示未知，不能按零费用或申请金额推算。", "接口权限标识为 open.merchant/orderdividequery；申请权限为 open.merchant/orderdivide。" ], "errors": [ { "message": "订单暂不可分账，请稍后查询", "http": 200, "when": "先查询原订单的 canDivide，确认业务条件后再提交。" }, { "message": "该订单存在未确认的分账申请，请先查询原申请", "http": 200, "when": "使用上一笔 divideRequestId 查询，不能更换请求号重复申请。" }, { "message": "分账总金额超过订单可用额度 / 分账总金额超过订单剩余可分账金额", "http": 200, "when": "核对 availableDivideAmount，减少本次申请金额。" }, { "message": "分账申请受理结果未确认，请使用原 divideRequestId 查询，勿换号重试", "http": 200, "when": "继续查询原申请；未查到不能认定原申请未受理。" }, { "message": "订单分账不支持参数 <字段>", "http": 200, "when": "按参数表提交，删除比例、发起方、解冻余款及其他未开放字段。" }, { "message": "商户不存在或无权访问", "http": 200, "when": "核对订单、出款商户及全部接收商户的应用归属。" }, { "message": "divideRequestId 已存在且归属或业务参数不一致", "http": 200, "when": "核对原申请，不能更改订单、金额、接收方、通知地址或应用重复提交。" }, { "message": "请稍后发起订单分账，勿频繁调用", "http": 200, "when": "支付成功后稍等，且同一订单分账申请至少间隔 3 秒。" } ] } } }, "/api/open.merchant/orderQuery": { "post": { "operationId": "open_orderQuery", "summary": "开放订单查询", "description": "查询当前应用发起的订单，返回订单金额、支付状态、费用与资金处理状态，以及剩余可分账金额。仅能查询当前应用的订单；金额为查询时点的快照，具体可用情况以 unSplitAmount 和 unSplitAmountQueriedAt 为准。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "orderId" ], "properties": { "orderId": { "type": "string", "description": "订单号；只能查询当前应用通过 prePay 创建的订单。", "maxLength": 64 } } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792713600", "nonce": "example-query-nonce", "sign": "请在服务端生成签名", "orderId": "OPEN_ORDER_20261023_001" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "使用下单返回的 order_id 或请求时提交的 orderId 查询；请求仍需携带公共参数并重新签名。", "unSplitAmount 为剩余可分账金额，单位元，以两位小数字符串返回。null 表示尚未取得有效金额，不可按零处理；0.00 表示确认剩余金额为零。", "unSplitAmountQueriedAt 是金额查询的 Unix 秒时间戳，未取得金额时为 0。建议轮询间隔不短于 5 秒。", "订单支付状态可能更新延迟。请结合已验签的支付结果通知确认；查询接口仅返回订单信息。", "订单总手续费查看 totalFee；unSplitAmount 不能直接按订单金额减总手续费推算，也不是商户账户余额。保留资金后续处理能力请先确认适用范围。" ], "errors": [ { "message": "订单不存在或无权访问", "http": 200, "when": "核对订单号和调用应用；仅支持查询本应用通过 prePay 创建的订单。" } ] } } }, "/api/open.merchant/accountBalanceQuery": { "post": { "operationId": "open_accountBalanceQuery", "summary": "商户全部账户余额查询", "description": "查询当前应用所属商户的全部账户余额及账户状态。资金账户、待结算账户和待分账账户分别展示，总余额不等于可出款金额。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo" ], "properties": { "channel": { "type": "string", "enum": [ "yibao" ], "description": "渠道标识，本接口必填 yibao。" }, "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" } } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792800000", "nonce": "每次请求生成新随机串", "sign": "请在服务端生成签名", "channel": "yibao", "merchantNo": "10000000002" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AccountBalanceQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可查询当前应用下的商户。若应用配置了 scope，需授权 open.merchant/accountbalancequery。", "金额为查询时点的余额，以两位小数字符串返回。查询余额不代表已完成分账或结算。", "无法取得有效金额或查询失败时返回 code=0、data=null；不能把查询失败当成零余额。建议轮询间隔不短于 5 秒。", "订单分账使用 orderQuery.unSplitAmount；余额分账使用商户资金账户余额，不能把全部账户总余额、待结算余额或订单可分账金额混用。", "FUND_ACCOUNT 表示商户资金账户。余额分账使用资金账户余额，是否可发起仍取决于应用权限、商户产品、账户状态及实际可用资金。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对 merchantNo 及当前应用归属；其他应用和未分配商户均不能查询。" }, { "message": "channel 必须填写 yibao", "http": 200, "when": "本接口 channel 仅支持 yibao。" }, { "message": "merchantNo 必须为有效的商户编号，最多 32 位", "http": 200, "when": "merchantNo 必须是字符串，允许字母、数字、下划线和连字符，最多 32 位。" }, { "message": "余额查询暂不可用，请稍后重试或联系平台核对商户配置", "http": 200, "when": "本次查询未成功，请稍后使用原查询条件重试；不要按零余额处理。" } ] } } }, "/api/open.merchant/settleBalanceQuery": { "post": { "operationId": "open_settleBalanceQuery", "summary": "商户待结算金额查询", "description": "查询当前应用所属商户的可结算金额、未结算总额，以及结算产品和账户明细。支持查询当前全部，或按指定截止时间查询。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo" ], "properties": { "channel": { "type": "string", "enum": [ "yibao" ], "description": "渠道标识，本接口必填 yibao。" }, "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" }, "operatePeriod": { "type": "string", "enum": [ "ALL", "PERIOD" ], "default": "ALL", "description": "ALL 查询当前全部；PERIOD 查询指定截止时间范围。" }, "endTime": { "type": "string", "format": "date-time", "maxLength": 25, "x-required-label": "条件必填", "description": "operatePeriod=PERIOD 时必填；ISO 8601 秒精度，必须带时区，如 2026-10-23T23:59:59+08:00，也支持 Z。ALL 时省略。" }, "tradeChannel": { "type": "string", "enum": [ "YEEPAY" ], "default": "YEEPAY", "description": "交易通道，当前仅支持 YEEPAY。" } } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792800000", "nonce": "每次请求生成新随机串", "sign": "请在服务端生成签名", "channel": "yibao", "merchantNo": "10000000002" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SettleBalanceQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可查询当前应用下的商户。若应用配置了 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，再重新生成签名。该查询不提供历史时点的账户余额回放。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对 merchantNo 及当前应用归属；其他应用和未分配商户均不能查询。" }, { "message": "channel 必须填写 yibao", "http": 200, "when": "本接口 channel 仅支持 yibao。" }, { "message": "merchantNo 必须为有效的商户编号，最多 32 位", "http": 200, "when": "merchantNo 必须是字符串，允许字母、数字、下划线和连字符，最多 32 位。" }, { "message": "余额查询暂不可用，请稍后重试或联系平台核对商户配置", "http": 200, "when": "本次查询未成功，请稍后使用原查询条件重试；不要按零余额处理。" }, { "message": "operatePeriod 仅支持 ALL、PERIOD", "http": 200, "when": "本阶段不接受 AMOUNT。" }, { "message": "PERIOD 必须填写有效 endTime，格式如 2026-10-23T23:59:59+08:00，须含时区", "http": 200, "when": "核对日期、时间及有效时区，PERIOD 不可省略。" }, { "message": "endTime 仅在 operatePeriod=PERIOD 时填写", "http": 200, "when": "ALL 查询省略 endTime。" }, { "message": "tradeChannel 当前仅支持 YEEPAY", "http": 200, "when": "使用 YEEPAY 或省略 tradeChannel。" } ] } } }, "/api/open.merchant/settleWayQuery": { "post": { "operationId": "open_settleWayQuery", "summary": "商户结算方式查询", "description": "查询当前应用所属商户已配置的结算方向及对应比例。一个商户可能有多个方向，按 settleWayList 中各项比例解释。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo" ], "properties": { "channel": { "type": "string", "enum": [ "yibao" ], "description": "渠道标识，本接口必填 yibao。" }, "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" } } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792800000", "nonce": "每次请求生成新随机串", "sign": "请在服务端生成签名", "channel": "yibao", "merchantNo": "10000000002" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SettleWayQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "查询成功", "time": "1792800000", "data": { "merchantNo": "10000000002", "settleWayList": [ { "settleWay": "BANKCARD", "settleWayName": "银行卡", "settleRatio": "80.00" }, { "settleWay": "ACCOUNT", "settleWayName": "资金账户", "settleRatio": "20.00" } ], "queriedAt": 1792800000 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可查询当前签名应用所属的商户；如应用限制 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 查询；配置了某种结算方向不代表资金已结算到账。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对商户编号与当前应用归属，其他应用及未分配商户均不可查询。" }, { "message": "channel 必须填写 yibao", "http": 200, "when": "本接口仅支持 channel=yibao。" }, { "message": "merchantNo 必须为有效的商户编号，最多 32 位", "http": 200, "when": "提交字符串商户编号，允许字母、数字、下划线和连字符，最多 32 位。" }, { "message": "请使用 POST 请求", "http": 200, "when": "按公共协议使用 POST 提交签名请求。" }, { "message": "结算方式查询暂不可用，请稍后重试或联系平台核对商户配置", "http": 200, "when": "本次查询未成功，请稍后重试；不要将失败结果解释为已设置银行卡结算。" } ] } } }, "/api/open.merchant/settleWayModifyRatio": { "post": { "operationId": "open_settleWayModifyRatio", "summary": "修改商户结算方向", "description": "为当前应用所属商户选择一个结算方向，后续结算时全部资金转至所选目标。每次仅选择一个方向，无需且不允许填写百分比。银行卡和合作银行账号须已添加为结算卡。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo", "settleWay" ], "properties": { "channel": { "type": "string", "enum": [ "yibao" ], "description": "渠道标识，必填 yibao。" }, "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可修改当前签名应用所属的商户。" }, "settleWay": { "type": "string", "enum": [ "BANKCARD", "ACCOUNT", "BANKACCOUNT", "FEE_ACCOUNT", "MARKET_ACCOUNT" ], "description": "选择一个结算方向：BANKCARD 银行卡；ACCOUNT 商户资金账户；BANKACCOUNT 合作银行账户；FEE_ACCOUNT 商户手续费账户；MARKET_ACCOUNT 商户营销账户。每次仅选择一个方向，后续结算时全部资金转至所选目标。" }, "bankCardNo": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "maxLength": 64, "x-required-label": "条件必填", "description": "BANKCARD/BANKACCOUNT 时必填，且已添加为结算卡；其他方向省略。银行卡方向填写已绑定完整卡号；合作银行方向填写开户返回的合作银行账号。禁止填写掩码或数值类型。" } }, "oneOf": [ { "properties": { "settleWay": { "enum": [ "BANKCARD", "BANKACCOUNT" ] } }, "required": [ "bankCardNo" ] }, { "properties": { "settleWay": { "enum": [ "ACCOUNT", "FEE_ACCOUNT", "MARKET_ACCOUNT" ] } }, "not": { "required": [ "bankCardNo" ] } } ], "not": { "anyOf": [ { "required": [ "settleRatio" ] }, { "required": [ "settleWayList" ] }, { "required": [ "settleWayRatioDetailDtoList" ] } ] } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792800000", "nonce": "每次请求生成新随机串", "sign": "请在服务端生成签名", "channel": "yibao", "merchantNo": "10000000002", "settleWay": "ACCOUNT" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SettleWayModifyRatioResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "修改成功", "time": "1792800000", "data": { "merchantNo": "10000000002", "status": "SUCCESS", "processedAt": 1792800000 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可修改当前签名应用所属的商户。应用限制 scope 时须授权 open.merchant/settlewaymodifyratio，查询接口授权不等于此修改接口授权。", "只提交一个 settleWay，后续结算时全部资金转至所选方向。不得传入 settleRatio、settleWayList 或其他结算方向列表。", "例如全部结算至资金账户，填写 settleWay=ACCOUNT；全部结算至已绑定银行卡，填写 settleWay=BANKCARD，并补充该卡的 bankCardNo。", "BANKCARD/BANKACCOUNT 须填写已添加为结算卡的完整账号，其他方向省略 bankCardNo；银行卡号须作为字符串传递。", "处理成功返回 code=1、data.status=SUCCESS。processedAt 为本次确认时间，不代表资金到账时间；修改后请调用 settleWayQuery 核对配置。", "超时或返回“结果未确认”时，修改可能已生效。先查询当前配置并核对目标，再决定是否重新提交；不要直接循环重试。", "本接口设置结算方向，不发起资金结算。账户余额、可结算金额分别使用 accountBalanceQuery 和 settleBalanceQuery 查询。", "响应不回显账号或户名。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对 merchantNo 和应用归属，其他应用及未分配商户均不可修改。" }, { "message": "channel 必须填写 yibao", "http": 200, "when": "填写 channel=yibao。" }, { "message": "merchantNo 必须为有效的商户编号，最多 32 位", "http": 200, "when": "提交字符串商户编号。" }, { "message": "settleWay 必须为单个受支持的结算方向", "http": 200, "when": "填写五种已支持方向之一，不能传数组、空值或未知方向。" }, { "message": "请求包含不支持的结算比例字段", "http": 200, "when": "删除 settleRatio 字段，仅通过 settleWay 选择一个结算方向。" }, { "message": "仅允许提交一个 settleWay，请勿传入结算方向列表", "http": 200, "when": "删除 settleWayList 及其他结算方向列表，仅提交单个 settleWay。" }, { "message": "银行卡或合作银行方向必须填写有效的完整 bankCardNo，最多 64 位", "http": 200, "when": "填写已经绑定的完整账号字符串，不能使用掩码。" }, { "message": "非银行卡或合作银行方向请省略 bankCardNo", "http": 200, "when": "ACCOUNT、FEE_ACCOUNT、MARKET_ACCOUNT 项省略账号字段。" }, { "message": "结算账户不存在或未开通", "http": 200, "when": "核对目标账号和产品开通情况。" }, { "message": "结算修改商户关系校验未通过", "http": 200, "when": "联系技术支持核对商户权限。" }, { "message": "结算修改请求重复，请先查询当前配置", "http": 200, "when": "查询当前配置确认前次结果，避免重复提交。" }, { "message": "结算方式修改结果未确认，请先查询当前配置后再决定是否重试", "http": 200, "when": "超时、异常响应或状态未确认；不能直接认定修改没有生效。" } ] } } }, "/api/open.merchant/selfSettleApply": { "post": { "operationId": "open_selfSettleApply", "summary": "自助结算申请", "description": "将待结算账户中当前符合结算条件的资金，按商户已配置的结算方向发起结算。银行卡方向结算至绑定银行卡，ACCOUNT 方向转入资金账户。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo", "settleRequestNo" ], "properties": { "channel": { "type": "string", "description": "渠道标识，必填 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "商户编号，仅限当前签名应用所属的商户。", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "settleRequestNo": { "type": "string", "description": "接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operatePeriod": { "type": "string", "description": "ALL 申请结算当前全部可结算资金；PERIOD 申请结算截至指定时间的可结算资金。当前不开放指定金额结算。", "enum": [ "ALL", "PERIOD" ], "default": "ALL" }, "endTime": { "type": "string", "description": "PERIOD 时必填；带时区的截止时间，例 2026-10-24T00:00:00+08:00；ALL 时省略。", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2})$", "x-required-label": "条件必填" }, "bankRemark": { "type": "string", "description": "银行附言，最多 32 字，不能包含换行或控制字符。", "maxLength": 32 }, "notifyUrl": { "type": "string", "maxLength": 2048, "description": "接收结算结果通知的公网 HTTP(S) 地址。选填；省略或为空字符串时不发送通知，可通过 settleRecordsQuery 查询结果。" } }, "oneOf": [ { "properties": { "operatePeriod": { "enum": [ "PERIOD" ] } }, "required": [ "operatePeriod", "endTime" ] }, { "properties": { "operatePeriod": { "enum": [ "ALL" ] } }, "not": { "required": [ "endTime" ] } } ], "not": { "anyOf": [ { "required": [ "settleAmount" ] }, { "required": [ "settleWay" ] }, { "required": [ "settleRatio" ] }, { "required": [ "settleWayList" ] }, { "required": [ "bankCardNo" ] }, { "required": [ "settleWayRatioDetailDtoList" ] }, { "required": [ "extInfo" ] }, { "required": [ "receiverMerchantNo" ] } ] } } ] }, "example": { "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" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SelfSettleApplyResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "code": 1, "msg": "结算申请已受理，请查询最终结果", "time": "1792800000", "data": { "merchantNo": "10000000002", "settleRequestNo": "SETTLE_20261024_0001", "settleOrderNo": "SETTLE_ORDER_EXAMPLE", "status": "ACCEPTED", "acceptedAt": 1792800000 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可操作当前签名应用所属商户；应用限制 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 秒，不支持暂停响应指令。详细规则及接收示例见异步通知章节。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对商户编号和当前应用归属。" }, { "message": "settleRequestNo 必须为 1 至 64 位字母、数字、下划线或连字符", "http": 200, "when": "提交商户内唯一、格式有效的字符串请求号。" }, { "message": "operatePeriod 仅支持 ALL、PERIOD", "http": 200, "when": "当前仅开放全部可结算资金和按截止时间结算，不支持 AMOUNT。" }, { "message": "自助结算申请不支持参数 <字段>，请按接口文档提交", "http": 200, "when": "删除指定金额、方向、账号、extInfo、receiverMerchantNo 等未开放字段；notifyUrl 按字段要求填写。" }, { "message": "endTime 仅在 operatePeriod=PERIOD 时填写", "http": 200, "when": "ALL 请求省略 endTime；PERIOD 必须填写。" }, { "message": "endTime 必须为带时区的 ISO 8601 秒精度时间", "http": 200, "when": "填写有效日期及明确时区，不支持无时区或毫秒。" }, { "message": "bankRemark 必须为不超过 32 字的单行字符串", "http": 200, "when": "缩短附言并移除控制字符。" }, { "message": "当前范围内无可结算明细", "http": 200, "when": "先查询可结算金额和产品周期；不代表商户账户没有余额。" }, { "message": "可结算账户余额不足", "http": 200, "when": "核对实时可结算资金及近期结算申请。" }, { "message": "结算金额未达起结金额", "http": 200, "when": "确认产品的起结金额规则。" }, { "message": "结算请求号重复，请使用原请求号查询结算记录", "http": 200, "when": "查询原申请；不要换号重新申请。" }, { "message": "结算申请受理结果未确认，请使用原 settleRequestNo 查询结算记录，勿换号重试", "http": 200, "when": "原申请可能已被受理，先查询和核对。" }, { "message": "settleRequestNo 已存在且归属或业务参数不一致", "http": 200, "when": "原业务请求号不得换应用或修改参数后再次申请；查询并核对原申请。" }, { "message": "notifyUrl 必须为字符串 / notifyUrl 地址无效", "http": 200, "when": "可省略、留空字符串或填写符合要求的公网 HTTP(S) 地址，不接受 null、私网、保留地址或跳转目标。" } ] }, "callbacks": { "settlementResult": { "{$request.body#/notifyUrl}": { "post": { "summary": "结算结果通知", "description": "通知采用 POST application/json。请先验签、核对商户及原请求号，使用 notify_id 去重，并按 version 处理通知顺序。业务处理成功后返回 HTTP 2xx 和纯文本 SUCCESS。通知失败会重试；同一版本的业务内容不变，timestamp、nonce、sign 可能不同。", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementResultNotification" }, "example": { "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 } } } }, "responses": { "200": { "description": "业务可靠处理后返回 HTTP 2xx 与纯文本 SUCCESS，忽略大小写和首尾空白；确认后结束当前 notify_id 的自动投递。其他响应、网络错误或超时按统一规则重试，同一通知最多自动投递 10 次（含首次）；无暂停响应指令。", "content": { "text/plain": { "schema": { "type": "string" }, "example": "SUCCESS" } } } }, "x-notification-policy": { "$ref": "#/x-notification-policy" } } } } } } }, "/api/open.merchant/settleRecordsQuery": { "post": { "operationId": "open_settleRecordsQuery", "summary": "结算记录查询", "description": "按原结算请求号，或按结算申请起止时间，查询当前应用所属商户的结算处理结果、到账明细和冲退情况。", "tags": [ "开放平台" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "channel", "merchantNo" ], "properties": { "channel": { "type": "string", "description": "渠道标识，必填 yibao。", "enum": [ "yibao" ] }, "merchantNo": { "type": "string", "description": "商户编号，仅限当前签名应用所属的商户。", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "settleRequestNo": { "type": "string", "description": "接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$", "x-required-label": "二选一" }, "settleRequestBeginTime": { "type": "string", "description": "结算申请起始时间；按时间查询时与截止时间一起填写，范围不超过 31 天。", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2})$", "x-required-label": "条件必填" }, "settleRequestEndTime": { "type": "string", "description": "结算申请截止时间；不能早于起始时间。", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2})$", "x-required-label": "条件必填" }, "tradeChannel": { "type": "string", "description": "当前仅支持 YEEPAY，可省略。", "enum": [ "YEEPAY" ], "default": "YEEPAY" } }, "anyOf": [ { "required": [ "settleRequestNo" ], "not": { "anyOf": [ { "required": [ "settleRequestBeginTime" ] }, { "required": [ "settleRequestEndTime" ] } ] } }, { "required": [ "settleRequestBeginTime", "settleRequestEndTime" ] } ], "not": { "required": [ "receiverMerchantNo" ] } } ] }, "example": { "app_id": "ak_example", "sign_type": "HMAC-SHA256", "timestamp": "1792800000", "nonce": "每次请求生成新随机串", "sign": "请在服务端生成签名", "channel": "yibao", "merchantNo": "10000000002", "settleRequestNo": "SETTLE_20261024_0001" } } } }, "responses": { "200": { "description": "HTTP 200 仍需检查 code；code=1 为本次处理成功，code=0 为业务失败。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SettleRecordsQueryResponse" }, { "$ref": "#/components/schemas/BusinessFailure" } ] }, "example": { "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 } } } } }, "401": { "description": "公共鉴权失败，code=0，data=null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "签名校验失败", "time": "1792740000", "data": null } } } }, "503": { "description": "防重放存储不可用，本次请求拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonResponse" }, "example": { "code": 0, "msg": "防重放服务暂不可用，请稍后重试", "time": "1792740000", "data": null } } } } }, "x-docs": { "status": "documented", "responseUnverified": false, "notes": [ "仅可查询当前签名应用所属商户；应用限制 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；未收到通知或需要确认结果时，请主动查询。" ], "errors": [ { "message": "商户不存在或无权访问", "http": 200, "when": "核对当前应用的商户归属。" }, { "message": "请填写 settleRequestNo，或同时填写结算申请起止时间", "http": 200, "when": "选择原请求号查询，或填写完整时间范围。" }, { "message": "settleRequestNo 必须为 1 至 64 位字母、数字、下划线或连字符", "http": 200, "when": "使用发起申请时的原业务请求号。" }, { "message": "结算申请时间范围须按先后填写且不能超过 31 天", "http": 200, "when": "缩小时间范围并核对先后顺序。" }, { "message": "settleRequestBeginTime / settleRequestEndTime 必须为带时区的 ISO 8601 秒精度时间", "http": 200, "when": "提供有效日期和明确时区，不支持无时区、毫秒或空值。" }, { "message": "tradeChannel 当前仅支持 YEEPAY", "http": 200, "when": "省略该参数或填写 YEEPAY。" }, { "message": "本接口不支持 receiverMerchantNo", "http": 200, "when": "删除该参数，仅查询当前应用商户。" }, { "message": "结算记录查询暂不可用，请稍后重试或联系平台核对", "http": 200, "when": "查询失败或暂未查到记录不代表结算申请失败，请继续使用原请求号核对结果。" } ] } } } }, "components": { "schemas": { "CommonRequest": { "type": "object", "properties": { "app_id": { "type": "string", "description": "应用标识；应用须启用并满足本接口 scope 与来源 IP 白名单。", "example": "ak_your_app_id" }, "sign_type": { "type": "string", "description": "本次签名算法；须与应用开通的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ], "default": "HMAC-SHA256" }, "timestamp": { "type": "string", "description": "每次请求生成当前秒级时间戳，允许偏差 ±300 秒；兼容毫秒时间戳。", "example": "运行时生成" }, "nonce": { "type": "string", "description": "每次请求生成新的随机串，同一应用 600 秒内不可重复。", "example": "每次请求生成新随机串" }, "sign": { "type": "string", "description": "对全部公共参数、业务参数和 URL 查询参数签名；剔除 sign 自身及空字符串/null。数组转未转义中文和斜杠的 JSON；保留值内的空格与引号。", "example": "由公共客户端计算" } }, "description": "", "required": [ "app_id", "timestamp", "nonce", "sign" ] }, "CommonResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0, 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "description": "业务数据，类型由具体接口定义；可能为对象、数组、字符串或 null。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "MerchantInfo": { "type": "object", "properties": { "mchName": { "type": "string", "description": "商户全称。", "example": "河南某某商贸有限公司", "minLength": 2, "maxLength": 255 }, "mchNameAbbr": { "type": "string", "description": "商户简称。", "example": "某某商贸", "minLength": 2, "maxLength": 255 }, "etpsAttr": { "type": "string", "description": "主体类型：1 个体工商户，2 企业，3 小微。", "example": "2", "enum": [ "1", "2", "3" ] }, "servicePhone": { "type": "string", "description": "客服电话，手机号或含区号的固定电话。", "example": "0371-88886666" }, "mccCode": { "type": "string", "description": "三级行业项的 id，取 mccList 返回的 id/value；与返回的 mcc_code 字段区别。", "example": "12" }, "contactName": { "type": "string", "description": "联系人姓名。", "example": "张三", "minLength": 2, "maxLength": 255 }, "contactPhone": { "type": "string", "description": "联系人电话。", "example": "13800138000" }, "contactEmail": { "type": "string", "description": "联系人邮箱。", "example": "zhangsan@example.com", "format": "email" }, "provinceCode": { "type": "string", "description": "注册地址省编码；企业/个体必填。", "example": "410000", "x-required-label": "条件" }, "cityCode": { "type": "string", "description": "注册地址市编码；企业/个体必填。", "example": "410100", "x-required-label": "条件" }, "districtCode": { "type": "string", "description": "注册地址区县编码；企业/个体必填。", "example": "410102", "x-required-label": "条件" }, "provinceName": { "type": "string", "description": "注册地址省名称。", "example": "河南省" }, "cityName": { "type": "string", "description": "注册地址市名称。", "example": "郑州市" }, "districtName": { "type": "string", "description": "注册地址区县名称。", "example": "中原区" }, "addressReg": { "type": "string", "description": "注册地址详细地址，2–255 字符。", "example": "某某街道 100 号 3 层", "minLength": 2, "maxLength": 255 }, "longitude": { "type": "string", "description": "经度。", "example": "113.62" }, "latitude": { "type": "string", "description": "纬度。", "example": "34.75" } }, "description": "商户基本资料；数字及日期字段按字符串提交。", "required": [ "mchName", "mchNameAbbr", "etpsAttr", "servicePhone", "mccCode", "contactName", "contactPhone", "provinceName", "addressReg" ] }, "LegalInfo": { "type": "object", "properties": { "artifName": { "type": "string", "description": "法人姓名。", "example": "张三" }, "artifCertifType": { "type": "string", "description": "证件类型，当前校验仅支持身份证 00。", "example": "00", "enum": [ "00" ], "default": "00" }, "artifCertifId": { "type": "string", "description": "法人身份证号。", "example": "410000199001011234" }, "artifPhone": { "type": "string", "description": "法人手机号。", "example": "13800138000" }, "certifIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "certifIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" } }, "description": "法人资料。", "required": [ "artifName", "artifCertifId", "artifPhone", "certifIdStartDate", "certifIdEndDate" ] }, "BusinessLicense": { "type": "object", "properties": { "businessLicense": { "type": "string", "description": "营业执照编号。", "example": "91410100MA3XXXXXXX" }, "businessLicenseType": { "type": "string", "description": "证件类型，当前仅支持营业执照 01。", "example": "01", "enum": [ "01" ] }, "businessLicenseStartDate": { "type": "string", "description": "营业执照有效期开始，YYYY-MM-DD。", "example": "2019-06-01" }, "businessLicenseEndDate": { "type": "string", "description": "营业执照有效期结束，YYYY-MM-DD 或“长期”。", "example": "2039-06-01" } }, "description": "企业/个体需提供，小微可省略。", "required": [ "businessLicense", "businessLicenseStartDate", "businessLicenseEndDate" ], "x-required-label": "条件" }, "SettlementInfo": { "type": "object", "properties": { "accountType": { "type": "string", "description": "0 对公账户，1 银行借记卡。", "example": "0", "enum": [ "0", "1" ] }, "accountNo": { "type": "string", "description": "结算账户号，保留为字符串。", "example": "6222021234567890123" }, "accountName": { "type": "string", "description": "结算账户户名。", "example": "河南某某商贸有限公司" }, "certificateType": { "type": "string", "description": "结算人证件类型。", "example": "00", "default": "00" }, "certificateNo": { "type": "string", "description": "结算人证件号码。", "example": "410000199001011234" }, "settleType": { "type": "string", "description": "当前仅支持法人结算 1。", "example": "1", "enum": [ "1" ] }, "bankCode": { "type": "string", "description": "总行编码，取 bankList.bank_code。", "example": "ABC" }, "bankName": { "type": "string", "description": "总行名称；可由 bankCode 查询补齐，建议明确提交。", "example": "中国农业银行" }, "bankProvince": { "type": "string", "description": "开户省编码。", "example": "410000" }, "bankProvinceName": { "type": "string", "description": "开户省名称。", "example": "河南省" }, "bankCity": { "type": "string", "description": "开户市编码。", "example": "410100" }, "bankCityName": { "type": "string", "description": "开户市名称。", "example": "郑州市" }, "subBankCode": { "type": "string", "description": "支行联行号，取 branchList.branch_no。", "example": "103491000018" }, "subBankName": { "type": "string", "description": "支行名称。", "example": "中国农业银行郑州中原支行" }, "mobileNo": { "type": "string", "description": "银行预留手机号。", "example": "13800138000" } }, "description": "结算资料。", "required": [ "accountType", "accountNo", "accountName", "certificateNo", "bankCode", "subBankCode", "subBankName", "mobileNo" ] }, "ChannelExtra": { "type": "object", "properties": { "addressBuss": { "type": "string", "description": "经营详细地址，必填；必须放在 channel_extra，放入 merchant 会被丢弃。", "example": "某某街道 100 号 3 层", "minLength": 2, "maxLength": 255 }, "busProvinceCode": { "type": "string", "description": "经营地址省编码。", "example": "410000" }, "busProvinceName": { "type": "string", "description": "经营地址省名称。", "example": "河南省" }, "busCityCode": { "type": "string", "description": "经营地址市编码。", "example": "410100" }, "busCityName": { "type": "string", "description": "经营地址市名称。", "example": "郑州市" }, "busDistrictCode": { "type": "string", "description": "经营地址区县编码。", "example": "410102" }, "busDistrictName": { "type": "string", "description": "经营地址区县名称。", "example": "中原区" }, "shopType": { "type": "string", "description": "入网角色：0 连锁分店、1 总店、2 普通商户、3 分账接收方、4 平台商、5 入驻商户。", "example": "2", "enum": [ "0", "1", "2", "3", "4", "5" ] }, "mchNameEn": { "type": "string", "description": "商户英文名，填写时 2–255 字符。", "example": "Example Trading", "minLength": 2, "maxLength": 255 } }, "description": "经营地址与渠道扩展。", "required": [ "addressBuss", "busProvinceName", "busCityName" ] }, "MerchantPictures": { "type": "object", "properties": { "legalFrontPic": { "type": "string", "description": "法人身份证正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/legalFrontPic.jpg" }, "legalBackPic": { "type": "string", "description": "法人身份证反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/legalBackPic.jpg" }, "businessLicensePic": { "type": "string", "description": "营业执照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/businessLicensePic.jpg" }, "shopGatePic": { "type": "string", "description": "门头照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/shopGatePic.jpg" }, "shopInsidePic": { "type": "string", "description": "店内照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/shopInsidePic.jpg" }, "cashierDeskPic": { "type": "string", "description": "收银台照文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/cashierDeskPic.jpg" }, "bankCardPic": { "type": "string", "description": "银行卡正面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/bankCardPic.jpg" }, "bankCardBackPic": { "type": "string", "description": "银行卡反面文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/bankCardBackPic.jpg" }, "bankAccountPermitPic": { "type": "string", "description": "开户许可证文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/bankAccountPermitPic.jpg" }, "shareCertificate": { "type": "string", "description": "分账证明文件路径，取 upload 返回的 data.url；按主体/账户/产品提供相应材料。", "example": "/uploads/20261023/shareCertificate.jpg" } }, "description": "按图片名称索引的对象，不是数组；具体图片必填条件需按商户资料清单确认。" }, "UboInfoList": { "type": "array", "items": { "type": "object", "properties": { "uboName": { "type": "string", "description": "受益人姓名。", "example": "张三" }, "uboIdCard": { "type": "string", "description": "受益人身份证号。", "example": "410000199001011234" }, "uboIdStartDate": { "type": "string", "description": "有效期开始日期，YYYY-MM-DD。", "example": "2015-01-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "uboIdEndDate": { "type": "string", "description": "有效期结束日期，YYYY-MM-DD；长期证件使用“长期”。", "example": "2035-01-01" }, "uboPhone": { "type": "string", "description": "受益人电话。", "example": "13800138000" }, "uboAddress": { "type": "string", "description": "受益人证件/联系地址。", "example": "河南省郑州市中原区某某街道 100 号" }, "uboFrontPicLocal": { "type": "string", "description": "身份证正面文件路径，取 upload 返回的 data.url。", "example": "/uploads/20261023/uboFront.jpg" }, "uboBackPicLocal": { "type": "string", "description": "身份证反面文件路径，取 upload 返回的 data.url。", "example": "/uploads/20261023/uboBack.jpg" } }, "description": "", "required": [ "uboName", "uboIdCard", "uboIdStartDate", "uboIdEndDate", "uboFrontPicLocal", "uboBackPicLocal" ] }, "description": "受益人资料。企业需按进件资料要求提供，小微可传空数组。", "x-required-label": "条件" }, "IndexResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "app_id": { "type": "string", "description": "当前应用标识。" }, "app_name": { "type": "string", "description": "当前应用名称。" }, "pong": { "type": "boolean", "enum": [ true ], "description": "鉴权与本次处理成功时为 true。" }, "echo": { "type": "string", "description": "原始字符串，缺省为空。" } }, "description": "", "required": [ "app_id", "app_name", "pong", "echo" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "RegisterResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "outMchNo": { "type": "string", "description": "进件请求号，用于 registerQry/update/modifyMerchant。" } }, "description": "", "required": [ "outMchNo" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "MccListResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "行业目录项 id；进件使用三级项 id。" }, "mcc_code": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "行业编码；进件填写三级项 id，不能与此字段混用。" }, "mcc_name": { "type": "string", "description": "行业名称。" }, "level": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "层级。" }, "pid": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "父级项 id。" }, "value": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "与 id 一致。" }, "name": { "type": "string", "description": "与 mcc_name 一致。" } }, "description": "" }, "description": "" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "AreaCodeResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "地区编码。" }, "value": { "type": "string", "description": "与 code 一致。" }, "name": { "type": "string", "description": "地区名称。" }, "level": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "地区层级。" } }, "description": "" }, "description": "" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "BankListResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "array", "items": { "type": "object", "properties": { "bank_code": { "type": "string", "description": "银行编码，填入 settlement.bankCode。" }, "value": { "type": "string", "description": "与 bank_code 一致。" }, "name": { "type": "string", "description": "银行名称。" }, "bank_no": { "type": "string", "description": "银行联行号。" } }, "description": "" }, "description": "" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "BranchListResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "array", "items": { "type": "object", "properties": { "branch_no": { "type": "string", "description": "支行联行号，填入 settlement.subBankCode。" }, "branch_name": { "type": "string", "description": "支行名称。" }, "value": { "type": "string", "description": "branch_no 与 branch_name 以短横线连接。" }, "name": { "type": "string", "description": "与 branch_name 一致。" } }, "description": "" }, "description": "" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "UploadResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "上传成功后的文件路径，填入进件 path 对应图片字段。" } }, "description": "", "required": [ "url" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "UpdateResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "string", "description": "操作成功时返回字符串“成功”。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "ModifyMerchantResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "required": [ "applicationNo", "applicationStatus" ], "properties": { "applicationNo": { "type": "string", "description": "资料变更申请单号，与查询时使用的 requestNo 不同。" }, "applicationStatus": { "type": "string", "description": "资料变更申请的处理状态。" } }, "additionalProperties": true } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "ModifyQryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "description": "业务处理结果，具体字段须在接入前确认。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "RegisterQryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "applicationStatus": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "进件状态：-1 待完善、0 待审核、1 成功、2 驳回、3 转人工、4 真实性待验证、5 待签合同、6 业务开通中；不是按数字大小推进。" }, "auditOpinion": { "type": "string", "description": "审核意见或驳回原因。", "nullable": true }, "requestNo": { "type": "string", "description": "对应 register 返回的 outMchNo。" }, "merchantNo": { "type": "string", "description": "进件成功后返回的商户号，用于支付。", "nullable": true }, "elecSignUrl": { "type": "string", "description": "合同签署地址。", "nullable": true }, "intentionAuthUrl": { "type": "string", "description": "真实性验证地址。", "nullable": true } }, "description": "", "required": [ "applicationStatus", "auditOpinion", "requestNo" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "MerchantStatusQryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "description": "业务处理结果，具体字段须在接入前确认。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "ChannelsResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "yibao": { "type": "string", "description": "易宝渠道显示名称。" } }, "description": "", "required": [ "yibao" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "WechatAuthApplyResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "required": [ "applymentId" ], "properties": { "applymentId": { "type": "string", "description": "认证申请单号；后续认证查询时作为 applyNo 提交。" } }, "additionalProperties": true } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "AlipayAuthApplyResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "required": [ "applymentId" ], "properties": { "applymentId": { "type": "string", "description": "认证申请单号；后续认证查询时作为 applyNo 提交。" } }, "additionalProperties": true } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "WechatAuthQryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "description": "业务处理结果，具体字段须在接入前确认。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "AlipayAuthQryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "description": "业务处理结果，具体字段须在接入前确认。" } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "PrePayResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ], "description": "1 成功，0 失败。HTTP 状态码需独立判断。" }, "msg": { "type": "string", "description": "本次处理提示或失败原因；当前没有统一的细分业务错误码。" }, "time": { "type": "string", "description": "Unix 秒级时间戳，以字符串返回。" }, "data": { "type": "object", "properties": { "response_arr": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "USER_SCAN 返回二维码内容字符串；H5_PAY 返回支付跳转链接字符串；公众号、小程序、生活号和微信 SDK 返回支付调起参数，可能为对象或 JSON 字符串，请按所选支付方式解析。" }, "pay_way": { "type": "string", "description": "请求的支付方式。" }, "channel": { "type": "string", "description": "支付渠道：WECHAT 微信，ALIPAY 支付宝。" }, "order_id": { "type": "string", "description": "订单号，用于查询和核对支付结果。" }, "unique_order_no": { "type": "string", "description": "支付流水号，尚未取得时为空字符串。" } }, "description": "", "required": [ "response_arr", "pay_way", "channel", "order_id", "unique_order_no" ] } }, "description": "", "required": [ "code", "msg", "time", "data" ] }, "BalanceDivideResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "msg": { "type": "string", "description": "处理提示。" }, "time": { "type": "string", "description": "Unix 秒级时间戳。" }, "data": { "type": "object", "properties": { "merchantNo": { "type": "string", "description": "出款商户号。" }, "divideRequestId": { "type": "string", "description": "原分账请求号。" }, "status": { "type": "string", "description": "ACCEPTED 仅表示受理，不代表各笔资金处理完成。", "enum": [ "ACCEPTED" ] }, "acceptedAt": { "type": "integer", "description": "受理确认的 Unix 秒时间戳。" }, "totalAmount": { "type": "string", "description": "申请分账总金额，不含可能额外承担的手续费。", "pattern": "^\\d+\\.\\d{2}$" }, "detailCount": { "type": "integer", "minimum": 1, "maximum": 30, "description": "申请明细数量。" }, "detailList": { "type": "array", "items": { "type": "object", "properties": { "detailId": { "type": "string", "description": "稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。", "maxLength": 64 }, "ledgerNo": { "type": "string", "description": "接收商户号。", "maxLength": 16 }, "ledgerType": { "type": "string", "description": "接收方类型。", "enum": [ "MERCHANT" ] }, "divideAmount": { "type": "string", "description": "申请分账金额，单位元。", "pattern": "^\\d+\\.\\d{2}$" }, "feeChargeSide": { "type": "string", "description": "本笔申请的手续费承担方式。", "enum": [ "OUTSIDE", "INSIDE" ] } }, "required": [ "detailId", "ledgerNo", "ledgerType", "divideAmount", "feeChargeSide" ] } } }, "required": [ "merchantNo", "divideRequestId", "status", "acceptedAt", "totalAmount", "detailCount", "detailList" ] } }, "required": [ "code", "msg", "time", "data" ] }, "BusinessFailure": { "type": "object", "required": [ "code", "msg", "time", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "msg": { "type": "string" }, "time": { "type": "string" }, "data": { "description": "业务失败详情，可能为 null；请结合 msg 判断失败原因。" } } }, "PaymentResultNotification": { "type": "object", "properties": { "app_id": { "type": "string", "description": "本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。", "example": "ak_your_app_id" }, "sign_type": { "type": "string", "description": "本次通知的签名方式，与该业务申请使用的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ] }, "timestamp": { "type": "string", "description": "本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。", "example": "运行时生成" }, "nonce": { "type": "string", "description": "本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。", "example": "每次请求生成新随机串" }, "sign": { "type": "string", "description": "对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。", "example": "由公共客户端计算" }, "notify_id": { "type": "string", "description": "固定通知标识，重试时不变；请使用此字段去重，避免重复处理业务。" }, "orderId": { "type": "string", "description": "订单号，对应下单时的 orderId；下单未传时为返回的生成值。" }, "merchantNo": { "type": "string", "description": "收款商户号。" }, "orderAmount": { "type": "string", "description": "原订单金额，单位元，两位小数；须与接入方订单核对。" }, "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "SUCCESS 表示该订单支付成功；请核对订单号与金额后处理业务。" }, "uniqueOrderNo": { "type": "string", "description": "支付流水号，可用于核对交易。" }, "paidTime": { "type": "string", "description": "支付成功时间，北京时间 yyyy-MM-dd HH:mm:ss。" }, "payChannel": { "type": "string", "enum": [ "WECHAT", "ALIPAY" ], "description": "本次支付渠道：WECHAT 微信，ALIPAY 支付宝。", "example": "WECHAT" }, "payWay": { "type": "string", "description": "本次订单的支付方式，与下单请求一致。", "example": "USER_SCAN", "enum": [ "USER_SCAN", "WECHAT_OFFIACCOUNT", "MINI_PROGRAM", "SDK_PAY", "ALIPAY_LIFE", "H5_PAY" ] }, "fundProcessType": { "type": "string", "enum": [ "REAL_TIME", "DELAY_SETTLE" ], "default": "REAL_TIME", "description": "下单时选择的资金处理方式。", "example": "REAL_TIME" }, "memo": { "type": "string", "maxLength": 256, "description": "下单时提交的业务备注原值。", "example": "外部订单备注 A&B" }, "businessInfo": { "type": "string", "maxLength": 4096, "x-max-bytes": 4096, "description": "下单时提交的 businessInfo 原始 JSON 字符串。", "example": "{\"externalOrderId\":\"EXT202610230001\",\"source\":\"open-api\"}" } }, "required": [ "app_id", "sign_type", "timestamp", "nonce", "sign", "notify_id", "orderId", "merchantNo", "orderAmount", "status", "uniqueOrderNo", "paidTime", "payChannel", "payWay", "fundProcessType", "memo", "businessInfo" ] }, "OrderQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "orderId", "merchantNo", "uniqueOrderNo", "orderAmount", "status", "payChannel", "payWay", "platformFee", "fundProcessType", "fundStatus", "notifyStatus", "paidAt", "memo", "businessInfo", "pricingMode", "paymentProduct", "totalFeeRate", "totalFee", "feeStatus", "unSplitAmount", "unSplitAmountQueriedAt", "canDivide", "availableDivideAmount" ], "properties": { "orderId": { "type": "string", "description": "订单号" }, "merchantNo": { "type": "string", "description": "收款商户号" }, "uniqueOrderNo": { "type": "string", "description": "支付流水号，尚未取得时为空。" }, "orderAmount": { "type": "string", "description": "订单金额，单位元，十进制字符串。" }, "unSplitAmount": { "type": "string", "nullable": true, "pattern": "^(?:0|[1-9][0-9]{0,7})\\.[0-9]{2}$", "description": "剩余可分账金额，单位元，固定两位小数字符串；null 表示未取得有效金额，不能按 0 处理；0.00 表示已确认没有剩余可分账金额。适用于支付成功后的分账场景，与账户余额不同。", "example": "99.40" }, "unSplitAmountQueriedAt": { "type": "integer", "minimum": 0, "description": "有效剩余可分账金额的查询时间，Unix 秒时间戳；未取得金额时为 0。金额为此时点的快照，同一订单最多复用 5 秒。", "example": 1792713600 }, "status": { "type": "integer", "description": "订单支付状态：0 待支付、1 已支付、2 失败、3 已取消、4 已过期。状态更新可能延迟；本次剩余金额查询不改变支付状态。" }, "payChannel": { "type": "string", "description": "支付渠道：WECHAT / ALIPAY。" }, "payWay": { "type": "string", "description": "下单支付方式。" }, "platformFee": { "type": "string", "description": "费用处理参考金额，单位元；订单总手续费以 totalFee 为准，费用是否确认见 feeStatus。" }, "fundProcessType": { "type": "string", "description": "接入方业务选择：REAL_TIME / DELAY_SETTLE。" }, "fundStatus": { "type": "string", "description": "资金处理状态；DELAY_SETTLE 模式下 RESERVED 表示余款保留待后续处理。" }, "notifyStatus": { "type": "string", "description": "向接入方发送支付通知的任务状态，独立于支付状态。" }, "paidAt": { "type": "integer", "description": "支付成功的 Unix 秒时间戳，未支付为 0。" }, "memo": { "type": "string", "description": "下单时的业务备注。" }, "businessInfo": { "type": "string", "description": "下单时的业务扩展信息，为 JSON 字符串或空字符串。" }, "pricingMode": { "type": "string", "enum": [ "LEGACY", "APP_TOTAL" ], "description": "计费类型：LEGACY 历史计费，APP_TOTAL 应用约定费率计费。" }, "paymentProduct": { "type": "string", "description": "本次交易对应的支付产品代码，历史订单可能为空。" }, "totalFeeRate": { "type": "string", "nullable": true, "description": "本次订单适用的总费率，以百分比表示；0.600000 表示 0.6%。历史订单可能为 null。" }, "totalFee": { "type": "string", "nullable": true, "description": "本次订单总手续费，单位元。历史订单可能为 null。" }, "feeStatus": { "type": "string", "enum": [ "LEGACY", "PENDING", "CONFIRMED", "REVIEW" ], "description": "费用状态：PENDING 待确认，CONFIRMED 已确认，REVIEW 待核对，LEGACY 历史计费。" }, "canDivide": { "type": "boolean", "description": "当前是否具备订单分账条件。金额是查询时点快照，申请时会重新校验；false 时不应提交分账。" }, "availableDivideAmount": { "type": "string", "description": "当前可申请订单分账的金额，单位元。未具备条件、存在未确认申请或金额未知时为 null；0.00 表示已确认没有可用额度。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true } } } } } ] }, "AccountBalanceQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "totalAccountBalance", "accountInfoList", "queriedAt" ], "properties": { "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" }, "totalAccountBalance": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "全部账户总余额，不能作为某一账户的可出款金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。" }, "accountInfoList": { "type": "array", "description": "实际返回的账户列表；缺少某类账户不代表其余额为零，不会补造账户。", "items": { "type": "object", "required": [ "accountType", "balance", "accountStatus" ], "properties": { "accountType": { "type": "string", "maxLength": 64, "description": "账户类型：SETTLE_ACCOUNT 待结算、FUND_ACCOUNT 商户资金、DIVIDE_ACCOUNT 待分账、FEE_ACCOUNT 手续费、MARKET_ACCOUNT 营销、SPECIAL_FUND_ACCOUNT 专款、DIVIDE_FUND_ACCOUNT 分账资金、DIVIDE_PENDING_ACCOUNT 分账在途。请兼容新增账户类型。" }, "balance": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "本账户余额，能否出款还需结合账户状态、产品权限及实际操作结果。 单位元，固定两位小数字符串；如存在负余额会保留负号。" }, "accountStatus": { "type": "string", "maxLength": 64, "description": "账户状态：AVAILABLE 可用、FROZEN 冻结、FROZEN_CREDIT 冻结止收、FROZEN_DEBIT 冻结止付、CANCELLATION 销户。请兼容新增状态。" }, "createTime": { "type": "string", "maxLength": 64, "description": "账户开户时间，取得时返回。" } } } }, "queriedAt": { "type": "integer", "minimum": 1, "description": "本次成功查询的 Unix 秒时间戳。金额仅为查询时点快照，不预占资金。" } } } } } ] }, "SettleBalanceQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "operatePeriod", "endTime", "tradeChannel", "settlableAmount", "unsettledAmount", "detailList", "queriedAt" ], "properties": { "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" }, "operatePeriod": { "type": "string", "enum": [ "ALL", "PERIOD" ], "description": "本次查询范围。" }, "endTime": { "type": "string", "nullable": true, "format": "date-time", "description": "PERIOD 返回北京时间的截止时间；ALL 返回 null。" }, "tradeChannel": { "type": "string", "enum": [ "YEEPAY" ], "description": "本次查询的交易通道。" }, "settlableAmount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "当前可结算但未结算的金额。变为零不代表结算成功，可能已生成结算记录或本身就没有可结算金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。" }, "unsettledAmount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "未结算总额，包含可结算但未结算金额，以及尚未到结算周期的金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。" }, "detailList": { "type": "array", "description": "按结算产品和账户返回的金额明细。", "items": { "type": "object", "required": [ "settleType", "accountType", "tradeChannel", "settlableAmount", "unsettledAmount" ], "properties": { "settleType": { "type": "string", "maxLength": 64, "description": "结算产品代码，当前使用 D1_MANUAL；请兼容其他已开通产品。" }, "accountType": { "type": "string", "maxLength": 64, "description": "结算账户类型，常见 SETTLE_ACCOUNT 待结算账户、DIVIDE_PENDING_ACCOUNT 分账在途账户、BASIC_ACCOUNT 基本账户。" }, "tradeChannel": { "type": "string", "enum": [ "YEEPAY" ], "description": "交易通道。" }, "settlableAmount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "该明细当前可结算金额。 单位元，固定两位小数字符串；如存在负余额会保留负号。" }, "unsettledAmount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "description": "该明细未结算总额。 单位元，固定两位小数字符串；如存在负余额会保留负号。" } } } }, "queriedAt": { "type": "integer", "minimum": 1, "description": "本次成功查询的 Unix 秒时间戳。金额仅为查询时点快照，不预占资金。" } } } } } ] }, "SettleWayQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "settleWayList", "queriedAt" ], "properties": { "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "商户编号，仅可查询当前签名应用所属的商户。" }, "settleWayList": { "type": "array", "description": "已配置的结算方向和比例列表，可能有多项；空列表不代表默认结算至银行卡。", "items": { "type": "object", "required": [ "settleWay", "settleWayName", "settleRatio" ], "properties": { "settleWay": { "type": "string", "enum": [ "BANKCARD", "ACCOUNT", "BANKACCOUNT", "FEE_ACCOUNT", "MARKET_ACCOUNT" ], "description": "BANKCARD 银行卡；ACCOUNT 资金账户；BANKACCOUNT 合作银行账户；FEE_ACCOUNT 手续费账户；MARKET_ACCOUNT 营销账户。" }, "settleWayName": { "type": "string", "enum": [ "银行卡", "资金账户", "合作银行账户", "手续费账户", "营销账户" ], "description": "结算方向的中文名称，与 settleWay 对应。" }, "settleRatio": { "type": "string", "pattern": "^(?:100\\.00|(?:[0-9]|[1-9][0-9])\\.[0-9]{2})$", "description": "该结算方向的比例，单位 %，范围 0.00 至 100.00，固定两位小数字符串。80.00 表示 80%。", "example": "100.00" } } } }, "queriedAt": { "type": "integer", "minimum": 1, "description": "本次成功查询的 Unix 秒时间戳，结算配置为此时点的快照。" } } } } } ] }, "SettleWayModifyRatioResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "status", "processedAt" ], "properties": { "merchantNo": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$", "description": "本次修改处理的商户编号。" }, "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "本次结算方向修改处理成功。" }, "processedAt": { "type": "integer", "minimum": 1, "description": "本次修改处理确认的 Unix 秒时间戳，不是结算到账时间。" } } } } } ] }, "SelfSettleApplyResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "settleRequestNo", "settleOrderNo", "status", "acceptedAt" ], "properties": { "merchantNo": { "type": "string", "description": "商户编号，仅限当前签名应用所属的商户。", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "settleRequestNo": { "type": "string", "description": "接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "settleOrderNo": { "type": "string", "description": "本次受理返回的结算订单号。", "maxLength": 64 }, "status": { "type": "string", "description": "ACCEPTED 仅表示结算申请已受理，不能据此标记到账。", "enum": [ "ACCEPTED" ] }, "acceptedAt": { "type": "integer", "description": "本次受理确认时间，Unix 秒时间戳。", "minimum": 1 } } } } } ] }, "SettleRecordsQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "required": [ "merchantNo", "settleRequestNo", "tradeChannel", "settleRecordList", "queriedAt" ], "properties": { "merchantNo": { "type": "string", "description": "商户编号，仅限当前签名应用所属的商户。", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "settleRequestNo": { "type": "string", "description": "接入方生成的结算业务请求号，在同一商户内须保持唯一。查询和故障确认始终使用原号，不能换号重试。", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$", "nullable": true }, "tradeChannel": { "type": "string", "description": "本次查询交易通道。", "enum": [ "YEEPAY" ] }, "settleRecordList": { "type": "array", "description": "本次条件下返回的全部结算记录；空列表表示暂未查到，不能据此认定申请失败。", "items": { "type": "object", "required": [ "summaryNo", "status", "statusName", "settleAmount", "realAmount", "realFee", "createTime", "settleType", "detailList" ], "properties": { "summaryNo": { "type": "string", "description": "结算记录订单号。", "maxLength": 64 }, "status": { "type": "string", "description": "结算订单状态：SUCCESS 结算成功；BEFORE_REMIT 待出款；SETTLE_FAIL 结算异常；REMITTING 银行处理中。", "enum": [ "SUCCESS", "BEFORE_REMIT", "SETTLE_FAIL", "REMITTING" ] }, "statusName": { "type": "string", "description": "结算订单状态的中文名称。" }, "settleAmount": { "type": "string", "description": "应结金额，单位元，固定两位小数。", "pattern": "^-?\\d{1,16}\\.\\d{2}$" }, "realAmount": { "type": "string", "description": "结算到账金额，元；未取得时为 null，不默认等于应结金额。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "realFee": { "type": "string", "description": "结算手续费，元；未知时为 null，明确为零时为 0.00。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "createTime": { "type": "string", "description": "结算订单创建时间，未返回时为 null。", "nullable": true, "maxLength": 64 }, "settleType": { "type": "string", "description": "结算产品；以本次记录为准，未返回时为 null。", "nullable": true, "maxLength": 64 }, "detailList": { "type": "array", "description": "全部到账明细，不折叠为其中一条；未取得明细列表时为 null，返回空列表时保持为空。", "nullable": true, "items": { "type": "object", "required": [ "status", "statusName", "realAmount", "accountType", "correct", "finishTime", "reverseTime" ], "properties": { "status": { "type": "string", "description": "到账明细状态：INIT 待处理；REMIT_PROCESS 银行处理中；REMIT_FAIL/ACCOUNTING_FAIL 出款失败；REMIT_SUCCESS/SUCCESS 已到账。", "enum": [ "INIT", "REMIT_PROCESS", "REMIT_FAIL", "ACCOUNTING_FAIL", "REMIT_SUCCESS", "SUCCESS" ] }, "statusName": { "type": "string", "description": "该明细状态的中文名称。" }, "realAmount": { "type": "string", "description": "该明细到账金额，元；未知时为 null，明确为零时为 0.00。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "accountType": { "type": "string", "description": "目标账户类型：DEBIT_CARD 借记卡、PUBLIC_CARD 对公账户、PASSBOOK 存折、UNIT_SETTLE_CARD 单位结算卡、BANKACCOUNT 银行账户、FEE_ACCOUNT 手续费账户、MARKET_ACCOUNT 营销账户、ACCOUNT 资金账户；未知时为 null。", "nullable": true, "maxLength": 64 }, "correct": { "type": "boolean", "description": "是否打款冲退。true 表示该笔发生冲退，不能仅凭成功状态判断资金仍已到账；null 表示未取得冲退标记。", "nullable": true }, "finishTime": { "type": "string", "description": "到账完成时间，未返回时为 null；保留查询结果时间文本。", "nullable": true, "maxLength": 64 }, "reverseTime": { "type": "string", "description": "冲退时间，未返回时为 null。", "nullable": true, "maxLength": 64 } } } } } } }, "queriedAt": { "type": "integer", "description": "本次查询时间，Unix 秒时间戳。", "minimum": 1 } } } } } ] }, "SettlementResultNotification": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "notify_id", "eventType", "version", "merchantNo", "settleRequestNo", "settleOrderNo", "settleStatus", "settleAmount", "realAmount", "feeAmount", "retreatFlag", "settleType", "detailList", "occurredAt", "sign_type", "timestamp", "nonce", "sign", "app_id" ], "properties": { "notify_id": { "type": "string", "description": "固定通知事件标识，重试不变；请持久化去重。", "maxLength": 64 }, "eventType": { "type": "string", "enum": [ "SETTLEMENT_RESULT" ], "description": "结算结果通知类型。" }, "version": { "type": "integer", "minimum": 1, "description": "同一商户、结算请求的单调递增通知版本；仅允许更高版本更新状态。" }, "merchantNo": { "type": "string", "description": "原申请商户编号。" }, "settleRequestNo": { "type": "string", "description": "原结算业务请求号。" }, "settleOrderNo": { "type": "string", "description": "已核实的结算订单号。" }, "settleStatus": { "type": "string", "enum": [ "SUCCESS", "SETTLE_FAIL", "RETREATED" ], "description": "SUCCESS 结算成功；SETTLE_FAIL 结算异常；RETREATED 已发生打款冲退，不能作为资金仍到账处理。" }, "settleAmount": { "type": "string", "description": "应结金额，单位元，固定两位小数。", "pattern": "^-?\\d{1,16}\\.\\d{2}$" }, "realAmount": { "type": "string", "description": "结算到账金额，元；未取得时为 null，不默认等于应结金额。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "feeAmount": { "type": "string", "description": "结算手续费，元；未知时为 null，明确为零时为 0.00。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "retreatFlag": { "type": "boolean", "nullable": true, "description": "true 表示冲退；false 表示本次明确未冲退；null 表示未取得标记。" }, "settleType": { "type": "string", "description": "结算产品；以本次记录为准，未返回时为 null。", "nullable": true, "maxLength": 64 }, "detailList": { "type": "array", "description": "全部到账明细，不折叠为其中一条；未取得明细列表时为 null，返回空列表时保持为空。", "nullable": true, "items": { "type": "object", "required": [ "status", "statusName", "realAmount", "accountType", "correct", "finishTime", "reverseTime" ], "properties": { "status": { "type": "string", "description": "到账明细状态：INIT 待处理；REMIT_PROCESS 银行处理中；REMIT_FAIL/ACCOUNTING_FAIL 出款失败；REMIT_SUCCESS/SUCCESS 已到账。", "enum": [ "INIT", "REMIT_PROCESS", "REMIT_FAIL", "ACCOUNTING_FAIL", "REMIT_SUCCESS", "SUCCESS" ] }, "statusName": { "type": "string", "description": "该明细状态的中文名称。" }, "realAmount": { "type": "string", "description": "该明细到账金额，元；未知时为 null，明确为零时为 0.00。", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "nullable": true }, "accountType": { "type": "string", "description": "目标账户类型：DEBIT_CARD 借记卡、PUBLIC_CARD 对公账户、PASSBOOK 存折、UNIT_SETTLE_CARD 单位结算卡、BANKACCOUNT 银行账户、FEE_ACCOUNT 手续费账户、MARKET_ACCOUNT 营销账户、ACCOUNT 资金账户；未知时为 null。", "nullable": true, "maxLength": 64 }, "correct": { "type": "boolean", "description": "是否打款冲退。true 表示该笔发生冲退，不能仅凭成功状态判断资金仍已到账；null 表示未取得冲退标记。", "nullable": true }, "finishTime": { "type": "string", "description": "到账完成时间，未返回时为 null；保留查询结果时间文本。", "nullable": true, "maxLength": 64 }, "reverseTime": { "type": "string", "description": "冲退时间，未返回时为 null。", "nullable": true, "maxLength": 64 } } } }, "occurredAt": { "type": "integer", "minimum": 1, "description": "本版本结果的确认时间，Unix 秒时间戳；重试时不变。timestamp 为本次通知发送时间。" }, "sign_type": { "type": "string", "description": "本次通知的签名方式，与该业务申请使用的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ] }, "timestamp": { "type": "string", "description": "本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。", "example": "运行时生成" }, "nonce": { "type": "string", "description": "本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。", "example": "每次请求生成新随机串" }, "sign": { "type": "string", "description": "对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。", "example": "由公共客户端计算" }, "app_id": { "type": "string", "description": "本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。", "example": "ak_your_app_id" } } } ] }, "BalanceDivideRequestDetail": { "type": "object", "properties": { "ledgerNo": { "type": "string", "description": "接收商户号，须为当前应用下已完成入网的商户。", "maxLength": 16 }, "ledgerType": { "type": "string", "description": "接收方类型，目前仅支持商户账户。", "enum": [ "MERCHANT" ] }, "divideAmount": { "type": "string", "description": "分账金额，单位元；使用大于零、最多两位小数的十进制字符串。", "pattern": "^\\d{1,16}(\\.\\d{1,2})?$" }, "feeChargeSide": { "type": "string", "description": "手续费承担方式。OUTSIDE：出款方额外承担；INSIDE：从接收方到账金额中扣除。是否适用取决于商户已开通的计费方式，实际费用及扣账、到账金额以结果为准。", "enum": [ "OUTSIDE", "INSIDE" ], "default": "OUTSIDE" }, "remark": { "type": "string", "description": "分账附言，最多 32 字，不得包含换行或控制字符。", "maxLength": 32 }, "divideReason": { "type": "string", "description": "分账说明，最多 40 字，不得包含换行或控制字符。", "maxLength": 40 } }, "required": [ "ledgerNo", "ledgerType", "divideAmount" ] }, "BalanceDivideRequestDetails": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "$ref": "#/components/schemas/BalanceDivideRequestDetail" } }, "BalanceDivideDetail": { "type": "object", "properties": { "detailId": { "type": "string", "description": "稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。", "maxLength": 64 }, "detailNo": { "type": "string", "description": "分账处理明细号，尚未取得时为 null。", "nullable": true, "maxLength": 64 }, "ledgerNo": { "type": "string", "description": "接收商户号。", "maxLength": 16 }, "ledgerType": { "type": "string", "description": "接收方类型。", "enum": [ "MERCHANT" ] }, "divideAmount": { "type": "string", "description": "申请分账金额，单位元。", "pattern": "^\\d+\\.\\d{2}$" }, "feeChargeSide": { "type": "string", "description": "本笔申请的手续费承担方式。", "enum": [ "OUTSIDE", "INSIDE" ] }, "status": { "type": "string", "description": "单笔处理状态；成功后发生冲退时仍可能变为 FAIL。", "enum": [ "PROCESSING", "SUCCESS", "FAIL" ] }, "reversed": { "type": "boolean", "description": "是否已确认本笔分账曾成功、之后转为失败。" }, "version": { "type": "integer", "minimum": 0, "description": "本明细的通知版本，尚无结果通知时为 0；不同明细分别计数。" }, "receiveAmount": { "type": "string", "description": "实际到账金额；尚未确认时为 null，不得按申请金额或零推算。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "debitAmount": { "type": "string", "description": "实际扣账金额；尚未确认时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "feeAmount": { "type": "string", "description": "实际分账手续费；尚未确认时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "finishTime": { "type": "string", "description": "结果中返回的完成时间；尚未取得时为 null。", "nullable": true }, "failReason": { "type": "string", "description": "失败原因，无失败原因时为空字符串。" }, "remark": { "type": "string", "description": "申请时填写的附言。" }, "divideReason": { "type": "string", "description": "申请时填写的分账说明。" } }, "required": [ "detailId", "detailNo", "ledgerNo", "ledgerType", "divideAmount", "feeChargeSide", "status", "reversed", "version", "receiveAmount", "debitAmount", "feeAmount", "finishTime", "failReason", "remark", "divideReason" ] }, "BalanceDivideQueryResponse": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "msg": { "type": "string", "description": "处理提示。" }, "time": { "type": "string", "description": "Unix 秒级时间戳。" }, "data": { "type": "object", "properties": { "merchantNo": { "type": "string", "description": "出款商户号。" }, "divideRequestId": { "type": "string", "description": "原分账请求号。" }, "status": { "type": "string", "description": "汇总状态。UNKNOWN：受理结果未确认；REJECTED：申请未受理；PROCESSING：仍有明细待确认；SUCCESS：当前全部成功；PARTIAL_SUCCESS：全部处理后部分成功；FAIL：当前全部失败。成功结果后续仍可能发生变化，须处理更新的结果通知。", "enum": [ "UNKNOWN", "REJECTED", "PROCESSING", "SUCCESS", "PARTIAL_SUCCESS", "FAIL" ] }, "totalAmount": { "type": "string", "description": "申请分账总金额，不含可能额外承担的手续费。", "pattern": "^\\d+\\.\\d{2}$" }, "detailCount": { "type": "integer" }, "successCount": { "type": "integer" }, "failCount": { "type": "integer" }, "processingCount": { "type": "integer" }, "acceptedAt": { "type": "integer", "description": "受理确认时间，Unix 秒时间戳；未确认时为 0。" }, "queriedAt": { "type": "integer", "description": "最后一次成功核对分账结果的 Unix 秒时间戳；尚未取得有效查询结果时为 0。" }, "detailList": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceDivideDetail" } }, "receiveAmount": { "type": "string", "description": "已确认的逐笔到账金额合计；任一明细金额未知时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "debitAmount": { "type": "string", "description": "已确认的逐笔扣账金额合计；任一明细金额未知时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "feeAmount": { "type": "string", "description": "已确认的逐笔手续费合计；任一明细金额未知时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true } }, "required": [ "merchantNo", "divideRequestId", "status", "totalAmount", "detailCount", "successCount", "failCount", "processingCount", "acceptedAt", "queriedAt", "detailList", "receiveAmount", "debitAmount", "feeAmount" ] } }, "required": [ "code", "msg", "time", "data" ] }, "BalanceDivideResultNotification": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "properties": { "detailId": { "type": "string", "description": "稳定的分账明细标识；通知去重及版本比较须按此明细分别处理。", "maxLength": 64 }, "detailNo": { "type": "string", "description": "分账处理明细号，尚未取得时为 null。", "nullable": true, "maxLength": 64 }, "ledgerNo": { "type": "string", "description": "接收商户号。", "maxLength": 16 }, "ledgerType": { "type": "string", "description": "接收方类型。", "enum": [ "MERCHANT" ] }, "divideAmount": { "type": "string", "description": "申请分账金额，单位元。", "pattern": "^\\d+\\.\\d{2}$" }, "feeChargeSide": { "type": "string", "description": "本笔申请的手续费承担方式。", "enum": [ "OUTSIDE", "INSIDE" ] }, "status": { "type": "string", "description": "单笔处理状态；成功后发生冲退时仍可能变为 FAIL。", "enum": [ "SUCCESS", "FAIL" ] }, "reversed": { "type": "boolean", "description": "是否已确认本笔分账曾成功、之后转为失败。" }, "version": { "type": "integer", "minimum": 1, "description": "同一 detailId 内递增的通知版本，从 1 开始；不同明细分别比较，较低版本不得覆盖新状态。" }, "receiveAmount": { "type": "string", "description": "实际到账金额；尚未确认时为 null，不得按申请金额或零推算。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "debitAmount": { "type": "string", "description": "实际扣账金额；尚未确认时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "feeAmount": { "type": "string", "description": "实际分账手续费；尚未确认时为 null。", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "finishTime": { "type": "string", "description": "结果中返回的完成时间；尚未取得时为 null。", "nullable": true }, "failReason": { "type": "string", "description": "失败原因，无失败原因时为空字符串。" }, "remark": { "type": "string", "description": "申请时填写的附言。" }, "divideReason": { "type": "string", "description": "申请时填写的分账说明。" }, "notify_id": { "type": "string", "description": "固定通知标识，重试不变。" }, "eventType": { "type": "string", "description": "通知类型。", "enum": [ "BALANCE_DIVIDE_RESULT" ] }, "merchantNo": { "type": "string", "description": "原出款商户号。" }, "divideRequestId": { "type": "string", "description": "原分账请求号。" }, "occurredAt": { "type": "integer", "description": "本版本结果的确认时间，Unix 秒时间戳；重试时不变。" }, "app_id": { "type": "string", "description": "本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。", "example": "ak_your_app_id" }, "sign_type": { "type": "string", "description": "本次通知的签名方式，与该业务申请使用的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ] }, "timestamp": { "type": "string", "description": "本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。", "example": "运行时生成" }, "nonce": { "type": "string", "description": "本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。", "example": "每次请求生成新随机串" }, "sign": { "type": "string", "description": "对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。", "example": "由公共客户端计算" } }, "required": [ "detailId", "detailNo", "ledgerNo", "ledgerType", "divideAmount", "feeChargeSide", "status", "reversed", "version", "receiveAmount", "debitAmount", "feeAmount", "finishTime", "failReason", "remark", "divideReason", "notify_id", "eventType", "merchantNo", "divideRequestId", "occurredAt", "app_id", "sign_type", "timestamp", "nonce", "sign" ] } ] }, "OrderDivideRequestDetails": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "required": [ "ledgerNo", "amount" ], "properties": { "ledgerNo": { "type": "string", "description": "接收商户编号，须属于同一应用且已完成入网及分账关系配置。", "maxLength": 11 }, "amount": { "type": "string", "description": "本笔分账金额，单位元，大于零，最多两位小数；请按字符串填写。", "pattern": "^(?:0|[1-9][0-9]{0,15})(?:\\.[0-9]{1,2})?$" }, "ledgerType": { "type": "string", "description": "商户间分账，省略时使用 MERCHANT2MERCHANT。", "enum": [ "MERCHANT2MERCHANT" ], "default": "MERCHANT2MERCHANT" }, "divideDetailDesc": { "type": "string", "description": "分账说明，单行文本，最多 128 个 UTF-8 字节。", "maxLength": 128, "x-max-bytes": 128 } } } }, "OrderDivideApplyResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "orderId", "merchantNo", "divideRequestId", "status", "totalAmount", "detailCount", "acceptedAt" ], "properties": { "orderId": { "type": "string", "description": "原支付订单号。" }, "merchantNo": { "type": "string", "description": "收款商户编号。" }, "divideRequestId": { "type": "string", "description": "你方分账请求号。" }, "status": { "type": "string", "description": "ACCEPTED 表示申请已受理，请继续查询最终结果。", "enum": [ "ACCEPTED" ] }, "totalAmount": { "type": "string", "description": "申请分账总金额，单位元。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$" }, "detailCount": { "type": "integer", "minimum": 1, "maximum": 5, "description": "本次申请的明细笔数。" }, "acceptedAt": { "type": "integer", "minimum": 0, "description": "申请受理时间，Unix 秒。" } } } } } ] }, "OrderDivideQueryResponse": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "orderId", "merchantNo", "divideRequestId", "status", "totalAmount", "detailCount", "acceptedAt", "version", "feeAmount", "receiveAmount", "finishTime", "queriedAt", "detailList" ], "properties": { "orderId": { "type": "string", "description": "原支付订单号。" }, "merchantNo": { "type": "string", "description": "收款商户编号。" }, "divideRequestId": { "type": "string", "description": "你方分账请求号。" }, "status": { "type": "string", "description": "UNKNOWN 结果未确认；PROCESSING 处理中；SUCCESS 整批成功；FAIL 整批失败；REJECTED 明确未受理。", "enum": [ "UNKNOWN", "PROCESSING", "SUCCESS", "FAIL", "REJECTED" ] }, "totalAmount": { "type": "string", "description": "申请分账总金额，单位元。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$" }, "detailCount": { "type": "integer", "minimum": 1, "maximum": 5, "description": "本次申请的明细笔数。" }, "acceptedAt": { "type": "integer", "minimum": 0, "description": "申请受理时间，Unix 秒。" }, "version": { "type": "integer", "minimum": 0, "description": "结果版本，按同一 orderId、divideRequestId 比较。" }, "feeAmount": { "type": "string", "description": "本批实际分账手续费合计；任何明细未确认时为 null。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "receiveAmount": { "type": "string", "description": "本批实际入账金额合计；任何明细未确认时为 null。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "finishTime": { "type": "string", "description": "分账完成时间；尚未取得为 null。", "nullable": true }, "queriedAt": { "type": "integer", "minimum": 0, "description": "最近有效结果查询时间，Unix 秒；尚无有效查询为 0。" }, "detailList": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "required": [ "detailId", "detailNo", "ledgerNo", "ledgerType", "amount", "feeAmount", "receiveAmount", "divideDetailDesc" ], "properties": { "detailId": { "type": "string", "description": "分账明细标识。" }, "detailNo": { "type": "string", "description": "分账成功后的明细流水号；尚未取得为 null。", "nullable": true }, "ledgerNo": { "type": "string", "description": "接收商户编号。" }, "ledgerType": { "type": "string", "description": "商户间分账。", "enum": [ "MERCHANT2MERCHANT" ] }, "amount": { "type": "string", "description": "申请金额，单位元。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$" }, "feeAmount": { "type": "string", "description": "实际分账手续费，单位元；null 表示尚未确认。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "receiveAmount": { "type": "string", "description": "实际入账金额，单位元；null 表示尚未确认。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "divideDetailDesc": { "type": "string", "description": "本笔分账说明。" } } } } } } } } ] }, "OrderDivideNotification": { "allOf": [ { "$ref": "#/components/schemas/CommonRequest" }, { "type": "object", "required": [ "orderId", "merchantNo", "divideRequestId", "status", "totalAmount", "detailCount", "acceptedAt", "version", "feeAmount", "receiveAmount", "finishTime", "detailList", "notify_id", "eventType", "sign_type", "timestamp", "nonce", "sign", "app_id" ], "properties": { "orderId": { "type": "string", "description": "原支付订单号。" }, "merchantNo": { "type": "string", "description": "收款商户编号。" }, "divideRequestId": { "type": "string", "description": "你方分账请求号。" }, "status": { "type": "string", "description": "本批分账最终状态。", "enum": [ "SUCCESS", "FAIL" ] }, "totalAmount": { "type": "string", "description": "申请分账总金额，单位元。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$" }, "detailCount": { "type": "integer", "minimum": 1, "maximum": 5, "description": "本次申请的明细笔数。" }, "acceptedAt": { "type": "integer", "minimum": 0, "description": "申请受理时间，Unix 秒。" }, "version": { "type": "integer", "minimum": 0, "description": "结果版本，按同一 orderId、divideRequestId 比较。" }, "feeAmount": { "type": "string", "description": "本批实际分账手续费合计；任何明细未确认时为 null。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "receiveAmount": { "type": "string", "description": "本批实际入账金额合计；任何明细未确认时为 null。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "finishTime": { "type": "string", "description": "分账完成时间；尚未取得为 null。", "nullable": true }, "detailList": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "required": [ "detailId", "detailNo", "ledgerNo", "ledgerType", "amount", "feeAmount", "receiveAmount", "divideDetailDesc" ], "properties": { "detailId": { "type": "string", "description": "分账明细标识。" }, "detailNo": { "type": "string", "description": "分账成功后的明细流水号；尚未取得为 null。", "nullable": true }, "ledgerNo": { "type": "string", "description": "接收商户编号。" }, "ledgerType": { "type": "string", "description": "商户间分账。", "enum": [ "MERCHANT2MERCHANT" ] }, "amount": { "type": "string", "description": "申请金额，单位元。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$" }, "feeAmount": { "type": "string", "description": "实际分账手续费，单位元；null 表示尚未确认。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "receiveAmount": { "type": "string", "description": "实际入账金额，单位元；null 表示尚未确认。", "pattern": "^(?:0|[1-9][0-9]{0,15})\\.[0-9]{2}$", "nullable": true }, "divideDetailDesc": { "type": "string", "description": "本笔分账说明。" } } }, "description": "本批分账全部明细，每项包含接收商户、申请金额、实际手续费及实际入账金额。" }, "notify_id": { "type": "string", "description": "通知唯一标识，重复通知保持不变。" }, "eventType": { "type": "string", "description": "通知类型。", "enum": [ "ORDER_DIVIDE_RESULT" ] }, "sign_type": { "type": "string", "description": "本次通知的签名方式，与该业务申请使用的签名方式一致。", "example": "HMAC-SHA256", "enum": [ "HMAC-SHA256", "RSA2" ] }, "timestamp": { "type": "string", "description": "本次通知发送的 Unix 秒级时间戳；重试时重新生成，验签允许偏差 300 秒。", "example": "运行时生成" }, "nonce": { "type": "string", "description": "本次通知的随机串，重试时重新生成；业务去重使用固定 notify_id。", "example": "每次请求生成新随机串" }, "sign": { "type": "string", "description": "对通知中除 sign 外的非空字段验签，排序、空值和 JSON 规则同公共协议。HMAC 使用本应用 app_secret；RSA2 使用平台提供的通知公钥，不能使用你方应用公钥。", "example": "由公共客户端计算" }, "app_id": { "type": "string", "description": "本次通知所属应用标识；须与你方该通知接收端使用的应用配置一致。", "example": "ak_your_app_id" } } } ] } } }, "x-notification-policy": { "contentType": "application/json", "acknowledgement": { "httpStatus": "2xx", "body": "SUCCESS", "caseSensitive": false, "trimWhitespace": true, "endsCurrentNotification": true }, "maxAttempts": 10, "includesInitialAttempt": true, "retryIntervalsSeconds": [ 10, 20, 40, 80, 160, 320, 640, 1280, 2560 ], "retryIntervalFrom": "previous failed delivery completion", "requestTimeoutSeconds": 15, "pauseSupported": false, "description": "适用于下列支付与资金结果通知；不适用于进件表单回调。确认仅结束当前 notify_id；新的业务结果版本可产生新通知。间隔为失败后的计划等待时间，实际到达可能延后。", "notifications": [ { "path": "/api/open.merchant/prePay", "anchor": "notify-payment", "title": "支付成功通知", "granularity": "每笔支付成功" }, { "path": "/api/open.merchant/orderDivide", "anchor": "notify-orderDivide", "title": "订单分账结果通知", "granularity": "按申请整批通知" }, { "path": "/api/open.merchant/balanceDivide", "anchor": "notify-balanceDivide", "title": "余额分账结果通知", "granularity": "按分账明细逐笔通知" }, { "path": "/api/open.merchant/selfSettleApply", "anchor": "notify-settlement", "title": "自助结算结果通知", "granularity": "按结算申请及结果版本通知" } ] } }