商户信息变更¶
文档说明¶
阅读对象¶
1、本规范的使用对象为服务商的技术开发人员、产品及业务。2、开发人员应该对post提交、json 格式、http/https传输、非对称秘钥和数据签名等有一定认识。
修订记录¶
2019-05-06：新增
相关术语¶
接口规则¶
协议规则¶
1、接口调用方式为http post。2、数据传输使用json格式，编码使用utf-8，请求时存放json串的参数名为: jsonData，接口传递中文或含有特殊字符的参数时应URL Encoding，接口接收返回参数时应做URL Decoding。3、如果json请求串中值为null，则json串格式应为{“test”: “”}。4、接口的除merPriv字段之外，其他所有字段不应该包含特殊字符，如：“&”、”?”和”‘’”等。5、后台通知商户返回应答参数的规则：为了表示商户交易系统已经收到交易应答，商户必须在应答接收页面输出一段特殊的字符串，组成规则为：固定字符串RECV_ORD_ID_加上交易应答中某一指定字段，指定字段请见具体接口商户应答参数。
安全规范¶
1、为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。2、详情请参见接口参数checkValue参数说明。3、checkValue生成规则：目前仅支持CFCA签名方式，checkValue生成方法请参考CFCA签名。简单示例：
HashMap<String , String> jsonDataMap = new HashMap<String , String>();
jsonDataMap.put("termOrdId" , "20180820020626985855");
jsonDataMap.put("memberId" , memberId);
jsonDataMap.put("ordAmt" , ordAmt);
jsonDataMap.put("authCode" , "134755413751742262");//二维码
jsonDataMap.put("goodsDesc" , URLEncoder.encode(goodsDesc , Constant.CHARSET_UTF8));
jsonDataMap.put("merPriv" , "{\"Ic\":\"2253425259\",\"merNoticeUrl\":\"http://172.31.13.182:38087/site/testHttp/testB/\",\"callType\":\"04\"}");
jsonDataMap.put("apiVersion" , apiVersion);
String jsonData = JSON.toJSONString(jsonDataMap);
// CFCA 签名
String checkValue = CFCASignature.signature("100001.pfx","888888", jsonData, "UTF-8").getSign();
商户信息变更¶
场景介绍¶
商户入驻信息填写有误时可调用商户基本信息修改接口修改对应信息。
功能描述¶
修改商户基本信息。D1手续费外扣业务配置。渠道商开通相关业务权限后商户才可执行（参考控台渠道商业务权限管理）。
业务流程¶
1、商户入驻完成。2、调用基本信息修改接口修改商户信息。
API列表¶
商户基本信息修改接口¶
输入参数¶
| 输入参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| jsonData | json | json | 必填 | jsonData数据，内容见下方描述 | |
| checkValue | 加签密文 | String | 必填 | 签名方式：CFCA | |
| JsonData | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| apiVersion | 版本号 | String(7) | 必填 | 固定：2.0.0.1 | |
| memberId | NSPOS商户号 | String(18) | 非必填 | 固定18位 ,汇付分配的商户号 | |
| agentId | 代理商号 | String(18) | 必填 | 代理商会员号 | |
| opTellerId | 代理商操作员 | String(32) | 必填 | 代理商操作员号 | |
| merchShortName | 商户简称 | String(32) | 非必填 | 简称格式：地区+商户名称+行业，
最大支持16位汉字
|
|
| provId | 经营地址所在省 | String(32) | 非必填 | 参照《智能收单商户入驻申请接口文档-
附录》中的《附录1 省份地区对照表》
比如河北省，请填写河北
|
|
| cityId | 经营地址所在市 | String(32) | 非必填 | 参照《智能收单商户入驻申请接口文档-
附录》中的《附录1 省份地区对照表》
比如唐山市，请填写唐山市
|
|
| areaId | 经营地址所在区县 | String(32) | 非必填 | 参照《智能收单商户入驻申请接口文档-
附录》中的《附录1 省份地区对照表》
比如XX区，请填写XX区
|
|
| merchAddr | 商户经营详细地址 | String(240) | 非必填 | 填写商户实际的经营详细地址。
长度说明：80个字符，最多40个汉字
|
|
| contactName | 商户联系人 | String(30) | 非必填 | 商户联系人姓名。支持少数名族,
联系人信息联动修改
|
|
contactId
Type
|
联系人证件类型 | String(2) | 非必填 | 选项:01:身份证、02:护照、04:军官证、
03:港澳台通行证、05:回乡证、
06:工商登记号、09:其他
|
|
| contactIdNo | 联系人证件号码 | String(40) | 非必填 | 联系人信息联动修改 | |
contactId
ValidType
|
联系人证件有效期 | String(1) | 非必填 | 选项：1，非长期；2，长期 | |
contactId
Sdate
|
联系人证件有效期
开始日期
|
String(8) | 非必填 | 日期格式要求：20180115 | |
| contactTelno | 联系人手机 | String(11) | 非必填 | 手机号格式 | |
| bankPhone | 银行卡预留手机号 | String(11) | 非必填 | 手机号格式 | |
| contactEmail | 联系人邮箱 | String(40) | 非必填 | 邮箱格式 | |
| csTel | 客服电话 | String(20) | 非必填 | 支持固话格式，手机格式 | |
| isPrivate | 结算账户类型 | String(1) | 非必填 | 选项：0.对公 1.对私 | |
| bankActName | 结算账户名 | String(30) | 非必填 | 结算账户名称 | |
| bankActId | 结算账号 | String(30) | 非必填 | 结账账号 | |
| bankProvId | 银行所在省 | String(32) | 非必填 | 参考《智能收单商户入驻申请接口文档-
附录》中的《附录1 省份地区对照表》
比如河北省，请填写河北
|
|
| bankCityId | 银行所在市 | String(32) | 非必填 | 参考《智能收单商户入驻申请接口文档-
附录》中的《附录1 省份地区对照表》
比如唐山市，请填写唐山市
|
|
| bankName | 银行名称 | String(32) | 非必填 | 参考《智能收单商户入驻申请接口文档-
附录》中的
附录2 区域银行支行对照表》
|
|
bankUnion
Code
|
银行联行号 | String(12) | 非必填 | 结算账户名联动修改 | |
| subBankName | 支行名称 | String(30) | 非必填 | 结算账户名联动修改 | |
| fee01 | D+1结算手续费(%) | String(1) | 必填 | 选择结算周期：D+1时必填 | |
| fee28 | T0结算手续费(%) | String(10) | 非必填 | 选择结算业务为01时必填(%) | |
| fee01MerId | D1外扣账户 | String(18) | 条件必填 | 选择结算业务为03时必填 | |
| settleRemark | 结算摘要 | String(200) | 非必填 | 默认为空如果需要自定义结算打款备注
请使用此字段传入，字段类型为字符串
|
|
| licType | 证照有效期 | String(1) | 必填 | 选项：1，非长期；2，长期 | |
| licSdate | 证照开始日期 | String(8) | 必填 | 日期格式要求：20180115 | |
| licEdate | 证照结束日期 | String(8) | 条件必填 | 选择非长期填写日期格式要求20180115 | |
| orgCode | 组织机构代码证 | String(10) | 条件必填 | 三证合一选择否填写 | |
| legalName | 法人 | String(20) | 条件必填 | 企业用户必填，法人姓名。
支持少数名族,最大支持20个汉字。
|
|
| idType | 法人证件类型 | String(2) | 条件必填 | 企业用户必填，选项：01:身份证02:护照
04:军官证03:港澳台通行证05:回乡证
06:工商登记号09:其他
|
|
| idNo | 法人证件号码 | String(40) | 条件必填 | 企业用户必填 | |
| idValidType | 法人证件有效期 | String(1) | 条件必填 | 企业用户必填，选项：1非长期；2长期 | |
| idSdate | 法人证件有效期
开始日期
|
String(8) | 条件必填 | 企业用户必填日期格式要求20180115 | |
| idEdate | 法人证件有效期
证件结束日期
|
String(8) | 条件必填 | 选择非长期填写日期格式要求20180115 | |
accountId
Type
|
持卡人证件类型 | String(2) | 条件必填 | 对私结算时必填 选项：01:身份证
02:护照、04:军官证03:港澳台通行证
05:回乡证06:工商登记号09:其他
|
|
| accountIdNo | 持卡人证件号码 | String(40) | 条件必填 | 对私结算时必填，持卡人证件号码 | |
accountId
ValidType
|
证件有效期 | String(1) | 条件必填 | 对私结算时必填 选项1:非长期;2:长期
持卡人信息联动修改
|
|
accountId
Sdate
|
证件有效期
开始日期
|
String(8) | 条件必填 | 对私结算时必填日期格式要求20180115
持卡人信息联动修改
|
|
account
IdEdate
|
证件有效期结束日期 | String(8) | 条件必填 | 选择非长期填写日期格式要求20180115
持卡人信息联动修改
|
|
| archFlph04 | 开户许可证 | String(60) | 非必填 | ||
| archFlph07 | 结算人身份证正面 | String(60) | 非必填 | ||
| archFlph08 | 结算人身份证反面 | String(60) | 非必填 | ||
| archFlph18 | 结算卡正面 | String(60) | 非必填 | ||
| archFlph19 | 结算卡反面 | String(60) | 非必填 | ||
| archFlph25 | 结算变更说明 | String(60) | 非必填 | 非必填 | |
| archFlph26 | 授权委托书 | String(60) | 非必填 | 非必填 | |
| archFlph27 | 结婚证照片原件 | String(60) | 非必填 | 非必填 | |
| archFlph28 | 户口本照片原件 | String(60) | 非必填 | 非必填 | |
| archFlph29 | 工商信息网
天眼信息网截图
|
String(60) | 非必填 | 非必填 | |
| archFlph30 | 水电煤账单 | String(60) | 非必填 | 非必填 | |
| archFlph31 | 租赁合同 | String(60) | 非必填 | 非必填 | |
| reqSerialNum | 请求流水号 | String(120) | 非必填 | 由接入方生成且保证唯一，查询时会用到 | |
| bgRetUrl | 异步通知地址 | String(120) | 非必填 | 审核结果异步通知推送地址 |
输出参数¶
| 输出参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| respCode | 返回码 | String(6) | 必填 | 选项：00000表示成功，其余表示失败 | |
| respDesc | 返回文字说明 | String(256) | 非必填 | ||
| checkValue | 加签密文 | String | 必填 | 加密算法使用：cfca签名 | |
| jsonData | Json字符串 | jsonData | 非必填 | jsonData数据，内容见下方描述 | |
| jsonData | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| memberId | NSPOS商户号 | String(18) | 非必填 | 固定18位 ,汇付分配的商户号 | |
| agentId | 代理商号 | String(18) | 必填 | ||
| applyNo | 商户申请单号 | String(18) | 必填 | ||
| reqSerialNum | 原请求流水号 | String(120) | 必填 | 由接入方生成且保证唯一，查询时使用 |
异步通知¶
基本信息修改接口异步通知
发布路径¶
bgRetUrl(接口上送时填写的异步通知地址)
输出参数¶
| 输出参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| respCode | 返回码 | String(6) | 必填 | 选项：00000表示成功，其余表示失败 | |
| respDesc | 返回文字说明 | String(256) | 非必填 | 开通失败，需要告知开通失败 | |
| checkValue | 加签密文 | String | 必填 | 加密算法使用：cfca签名 | |
| jsonData | Json字符串 | jsonData | 非必填 | jsonData数据，内容见下方描述 | |
| jsonData | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| reqSerialNum | 原请求流水号 | String(120) | 必填 | 由接入方生成且保证唯一，查询时使用 | |
| memberId | NSPOS商户号 | String(18) | 非必填 | 固定18位 ,汇付分配的商户号 | |
| agentId | 代理商号 | String(18) | 必填 | ||
| applyNo | 商户申请单号 | String(18) | 必填 | ||
| 商户应答参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| reqSerialNum | 请求流水号 | String | 必填 | RECV_ORD_ID_{ reqSerialNum } |
D1手续费外扣业务配置接口¶
输入参数¶
| 输入参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| checkValue | 加签密文 | String | 必填 | CFCA方式获取 | |
| jsonData | json | json | 必填 | jsonData数据，内容见下方描述 | |
| JsonData | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| apiVersion | 版本号 | String(7) | 必填 | 2.0.0.1 | |
| agentId | 代理商会员号 | String(18) | 必填 | 最长18位，该代理商号必须为商户号对应
的直属代理商号，否则校验不通过
|
|
| memberId | 商户会员号 | String(18) | 必填 | 最长18位 | |
d1FeeOuter
Auth
|
是否开通D1
手续费外扣业务
|
String | 必填 | 1：开通；0：关闭 | |
| d1FeeMerId | D1手续费外扣
账户
|
String | 条件必填 | 最长18位D1结算手续费外扣账户必须为商户
归属于体系内的渠道商/代理商
（代理商的上级代理商），
当d1FeeOuterAuth为1：开通时必填
|
输出参数¶
| 输出参数 | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
| respCode | 返回码 | String | 必填 | 000000表示成功，其余表示失败
000093 表示请求参数不规范
000095 表示验签失败
000107 表示相关业务权限不满足
000112 表示商户号对应的商户信息不存在
000115 表示商户结算信息不存在
000099 表示系统错误，可稍后重试
|
|
| respDesc | 返回描述 | String | 必填 | 具体返回描述信息，如：请求参数不规范 | |
| checkValue | 加签密文 | String | 必填 | CFCA方式获取 | |
| jsonData | json | json | 必填 | jsonData数据，内容见下方描述 | |
| JsonData | 参数代码 | 参数名称 | 数据类型 | 是否必填 | 参数说明 |
d1FeeOuter
Auth
|
是否开通D1
手续费外扣业务
|
String | 必填 | 1：开通；0：关闭 | |
| d1FeeMerId | D1手续费外扣
账户
|
String | 条件必填 | 同输入参数，透传
|
错误码¶
错误码¶
常见错误码描述，如还未解决问题请及时联系专业技术支持人员。
错误码 描述 错误码 描述 错误码 描述
000000 操作成功 000098 请求参数非法 000267 接口获取状态与订单状态不符
000093 请求参数不规范 000097 数据库异常 000268 二维码反向交易超时
000094 重复交易 000234 订单生成失败 000272 订单查询，未查询到记录
000095 验签失败 000236 PA入账失败 000273 支付通道类型不为微信或者支付宝
000100 业务系统已关闭 000238 对象属性复制异常 000277 无此交易类型
000107 业务系统不存在 000240 冻结账务对象不存在，分账串解析为空 000278 无此交易记录
000202 订单已存在 000241 订单被风控拒绝,风控未通过 000279 退货失败，该笔订单非退货交易
000203 原订单不存在 000242 风控系统调用异常 000197 控台系统异常，网络繁忙
000204 撤销金额与原订单金额不一致 000243 撤销或退货失败，PA冻结超时 000281 交易处理中
000205 撤销日期与原订单日期不一致 000244 不存在该账务类型 000099 网络繁忙，请稍后再试
000206 撤销失败，账务状态异常 000245 分账串异常 000219 订单校验失败
000207 撤销失败，PA冻结失败 000250 退货失败，PA退款失败 000220 签名上送失败，订单未完成支付
000208 撤销失败，通道失败 000256 退货失败，PA冻结超时 000221 签名上传失败，已上传
000209 撤销失败，原订单未完成 000255 确认交易失败,账务状态异常 000213 退货失败，超出退货期限
000210 退货失败，原订单未完成 000257 确认交易失败，原订单未成功 000214 退货失败，PA冻结失败
000211 退货失败，账务状态异常 000258 确认交易失败,确认金额与原交易金额不一致 000215 退货失败，通道失败
000212 退货失败，超出可退货金额 000260 消费撤销发通道扣款超时 000261 消费退货发通道扣款超时
000199 二维码交易处理中 000198 二维码交易失败