被分账方入网

功能概述

首信易支付子商户入网接口用于平台类商户为平台商品或服务的真实经营者进行开户注册。

接口地址

https://apis.5upay.com/serviceprovider/declaration/declare

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
merchantId 商户编号 varchar(9) 商户在首信易系统的唯一id,可在商户后台查看 M
requestId 请求号 varchar(50) 请求号为商户自行拟定,提交的请求号必须在自身平台交易中唯一。首信易支付系统已付或撤销的订单,商户平台不能以相同的请求号再次提交。 M
operationType 操作类型 固定值 CREATE 创建 M
MODIFY 更新
(当子商户入网的审核状态为NO_PASS时,根据审核备注信息,传此参数进行修改,requestId与创建时相同)
notifyUrl 通知地址 varchar(200) 服务器通知:当入网状态为终态后首信易服务器会向该地址发送通知,该地址可以带参数,如:http://www.5upay.com/callback.action?test=test。 M
extendedParameters 扩展参数 固定值 sendActiveEmail是否发送激活邮件 TRUE 是 FALSE 否 M
baseInfo 商户基本信息 Json 见下方商户基本信息表 M
bankCardInfo 结算信息 Json 见下方结算信息表 M
certificateInfo 商户资质信息 Json 见商户资质信息表 M
contractInfo 商户合同信息 Json 见商户合同信息表 M
settlementProfile 商户结算配置信息 Json 见商户结算配置信息表(清算方式选择结算时必传) C
hmac 参数签名 varchar(500) 商户生成的参数签名结果,获取hmac的方法请参考请求加密流程 M

本接口资质信息上传需要配合ftp使用,详见开发者服务-Sftp数据传输说明

请求参数(baseInfo,商户基本信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
signedType 商户入网类型 固定值 BY_SPLIT_BILL 被分账方 M
signedName 签约名称 varchar(80) 签约名称(当商户签约性质为自然人时,签约名称为自然人姓名。当商户结算银行卡属性为对公时,签约名称与结算账户开户名称一致,如有括号,请严格区分全角半角) M
registerRole 商户签约性质 固定值 INDIVIDUAL_BUSINESS 个体工商户 M
PUBLIC_INSTITUTIONS 事业单位
PRIVATE_NON_ENTERPRISE_ORGANIZATIONS 民办非企业组织
SOCIAL_ORGANIZATION 社会团体
UNINCORPORATED_ENTERPRISE 非法人企业
ENTERPRISE_LEGAL_PERSON 企业法人
NATURAL_PERSON自然人
GOVERNMENT_AGENCIES 政府机关
OTHERS 其他
cerType 证书类型 固定值 UNIFORM_SOCIAL_CREDIT_CODE 统一社会信用代码证 C
PRIVATE_NON_ENTERPRISE_UNIT_REGISTRATION_CERTIFICATE 民办非企业单位登记证书
INDIVIDUAL_BUSINESS_LICENCE 个体工商户营业执照
CERTIFICATE_OF_REGISTRATION_OF_SOCIAL_GROUP_LEGAL_PERSON 社会团体法人登记证书
LEGAL_PERSON_CERTIFICATE_OF_INSTITUTION 事业单位法人证书
FUND_LEGAL_PERSON_REGISTRATION_CERTIFICATE 基金法人登记证书
ID_CARD 身份证
BUSINESS_LICENSE 营业执照
OTHERS 其他
当签约性质不为自然人时必传
signedShorthand 商户简称 varchar(20) 商户简称 M
businessAddressProvince 经营地址省 varchar(6) 见编码表,当商户签约性质为自然人时,传入自然人身份证住址信息 M
businessAddressCity 经营地址市 varchar(6) 见编码表,当商户签约性质为自然人时,传入自然人身份证住址信息 M
businessAddressArea 经营地址区 varchar(6) 见编码表,当商户签约性质为自然人时,传入自然人身份证住址信息。如果选择的省市只有两级没有下一级时可不传此字段 C
businessAddress 经营地址 varchar(200) 商户详细经营地址,当商户签约性质为自然人时,传入自然人身份证住址信息 M
contactName 联系人姓名 varchar(50) 联系人姓名 M
contactEmail 联系人邮箱 varchar(100) 联系人邮箱 M
contactPhone 联系人电话 varchar(11) 联系人电话 M
businessClassification 业务分类 固定值 见编码表,此项分为一级和二级,传递此参数时需要用下划线拼接一级和二级业务分类,例如:一级为:LIFE_SERVICE,二级为:08, 传递参数则是:LIFE_SERVICE_08
(商户入网类型为收单子商户时必传,被分账方默认取父商户)
C
belongAgentNumber 所属代理商编 varchar(9) 所属代理商的商户编号 O

请求参数(bankCardInfo,结算信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
bankName 开户行名称 varchar(50) 开户行名称(结算银行卡属性为对公时必填) C
bankBranchName 支行名称 varchar(80) 支行名称(结算银行卡属性为对公时必填) C
accountName 开户名称 varchar(80) 开户名称 M
bankCardNo 开户账号 varchar(80) 开户账号(中国农业银行对公账户需在账户前添加两位省市编码,可咨询开户银行获取此编码) M
accountType 结算银行卡属性 固定值 PUBLIC 对公 C
PRIVATE 对私
(商户签约性质为个体工商户时必填,个人默认对私,企业等默认对公)
liquidationType 清算方式 固定值 SETTLE 结算 C
WITHDRAW 提现
不传默认结算
withdrawRateType 提现费率类型 固定值 SINGLE 单笔 C
RATE 百分比
清算方式选择提现时必传
withdrawRate 提现费率 varchar(20) 若计费种类为单笔时,可以支持填写到小数点后两位;若计费种类为百分比时,可以支持填写到小数点后四位(清算方式选择提现时必传) C
reservedPhoneNo 银行预留手机号 varchar(11) 银行预留手机号是对私结算卡在银行开户时预留的手机号 C

请求参数(desireAuthInfo,开户意愿核实信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
legalPersonName 法人姓名 varchar(50) 法人姓名 C
legalPersonIdNo 法人身份证号 varchar(20) 法人身份证号 C
legalPersonPhoneNo 意愿核实法人手机号 varchar(11) 法人手机号,若使用电子签约,则意愿核实法人手机号需要与电子签约法人手机号一致 C

请求参数(certificateInfo,商户资质信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
legalPersonName 法人姓名 varchar(50) 法人姓名 M
profession 法人职业 varchar(10) 见编码表(商户类型为自然人时必传) C
legalPersonPhone 电子签约法人手机号 varchar(11) 合同类型为电子签时或使用银行电子账户时必填,必须为法人的手机号或结算卡银行预留手机号。当银行预留手机号有值时,电子签约法人手机号必须使用银行预留手机号 C
legalPersonIdType 法人证件类型 固定值 IDCARD 身份证 M
PASSPORT 护照
OFFICERPASS 军官证
ARMEDPOLICE 武警证
HM_VISITORPASS 港澳居民往来内地通行证
RESIDENCEBOOKLET 户口簿
T_VISITORPASS 台湾居民来往大陆通行证
FOREIGNESTAYFOREVER 外国人永久居留证
OTHER 其它证件号
legalPersonIdNo 证件号码 varchar(20) 证件号码 M
idEffectiveDateStart 法人证件有效期开始日期 varchar(10) 格式:yyyy-MM-dd,例:2020-08-03 M
idEffectiveDateEnd 法人证件有效期结束日期 varchar(10) 格式:yyyy-MM-dd,例:2030-08-03。若为长期可传 2099-12-31 M
cerNo 资质证书编号 varchar(20) 资质证书编号 (商户类型不为自然人时必传) C
sellingArea 营业面积 固定值 A:500平米以上 C
B:200-500平米(含)
C:200平米以下
商户类型不为自然人时必传
staffSize 公司员工规模 固定值 A:100人以上 C
B:50-100人(含)
C:50人以下
商户类型不为自然人时必传
businessLicensePath 营业执照照片路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(商户类型不为自然人时必传,最大不超过1M,格式限制为jpg,png,bmp) C
openAccountPath 开户许可证照片路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(商户类型不为自然人及个体工商户时必传,为个体工商户时此项和legalPersonBankCardPath二选一进行传递,最大不超过1M,格式限制为jpg,png,bmp) C
legalIdCardProsPath 法人证件人像面路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(最大不超过1M,格式限制为jpg,png,bmp) M
legalIdCardConsPath 法人证件国徽面路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(最大不超过1M,格式限制为jpg,png,bmp) M
legalPersonBankCardPath 法人银行卡图影印件路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(商户类型为自然人时必传,为个体工商户时,结算银行卡属性为对私,此项必填。结算银行卡属性为对公,此项和openAccountPath二选一进行传递,最大不超过1M,格式限制为jpg,png,bmp) C
otherCerPath 其他资质文件路径 varchar(200) 需上传到sftp,见开发者服务-sftp数据传输说明(最大不超过5M,格式限制为AVI、mov、rmvb、rm、FLV、mp4、3GP、jpg、jpeg、png、pdf、ZIP、RAR) C

请求参数(contractInfo,商户合同信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
receiverName 收件人 varchar(50) 收件人 C
receiverPhone 收件人电话 varchar(20) 收件人电话 C
receiverAddress 收件人地址 varchar(200) 收件人地址 C
contractType 合同类型 固定值 ELECTRON 电子签 C
PAPER 纸质合同
CUSTOM 自定义签约
默认为“纸质合同”,选择“电子签”时将授权首信易通过电子签名的方式进行签约,无需邮寄合同。
商户入网类型为被分账方时必传电子签或自定义签约,自定义签约需要提前与我司约定好协议内容才可以使用。

请求参数(settlementProfile,商户结算配置信息)

参数名称 参数中文名称 类型& 长度 参数说明 是否必填
settleMode 结算方式 固定值 REGULAR_SETTLE:定期结算 C
SETTLE:自助结算
收单商户必填
被分账商户选填,不传默认定期结算
minAmount 最低结算金额 varchar(10) 最低结算金额默认为0 C
cycleType 定期结算类型 固定值 BYMONTH月结 C
BYWEEK周结
结算方式为定期结算时可传,如不传默认周结
cycleData 结算日期 固定值 周结可传1-7的数字 C
月结1-28的数字
如不传默认为1,2,3,4,5,6,7
holidaySettleIdentify 节假日是否出款 固定值 TRUE 是 O
FALSE 否
默认节假日出款为TRUE

注意:以上参数值中不能包含以下特殊字符 ' " & < > ( ) 空格

参数示例

{ "bankCardInfo": { "accountName": "接口入网子商户", "accountType": "PUBLIC", "bankBranchName": "大望路支行", "bankCardNo": "999999999", "liquidationType": "SETTLE", "withdrawRate": "0.10", "withdrawRateType": "SINGLE", "reservedPhoneNo": "136****1154" }, "baseInfo": { "businessAddress": "朝阳区大望路金地中心", "businessAddressArea": "130184", "businessAddressCity": "130100", "businessAddressProvince": "130000", "businessClassification": "LIFE_SERVICE_08", "cerType": "UNIFORM_SOCIAL_CREDIT_CODE", "contactEmail": "test@payease.com", "contactName": "联系人姓名", "contactPhone": "136****1154", "desireAuth": "DESIRE_NONEED", "registerRole": "INDIVIDUAL_BUSINESS", "signedName": "接口入网子商户", "signedShorthand": "简称", "signedType": "GENERAL_SUB_MERCHANT" }, "certificateContacts": [ { "address": "大望路", "effectiveDateEnd": "2019-10-10", "effectiveDateStart": "2018-10-10", "equityRatio": "0.15", "idNo": "987654321147850018", "idType": "IDCARD", "name": "受益人" } ], "certificateInfo": { "appName": "测试App", "appPath": "/serviceprovider/111.png", "businessLicensePath": "/serviceprovider/111.png", "cerEffectiveDateEnd": "2019-10-10", "cerEffectiveDateStart": "2018-10-10", "cerNo": "W11111888", "desireAuthPath": "/serviceprovider/111.mov", "holdingIdCardPath": "/serviceprovider/111.png", "icp": "QWER1234", "idEffectiveDateEnd": "2019-10-10", "idEffectiveDateStart": "2018-10-10", "legalIdCardConsPath": "/serviceprovider/111.png", "legalIdCardProsPath": "/serviceprovider/111.png", "legalPersonIdNo": "140***********2336", "legalPersonIdType": "IDCARD", "legalPersonName": "创始人", "openAccountPath": "/serviceprovider/111.png", "otherCerPath": "/serviceprovider/111.png", "profession": "11", "sellingArea": "A", "staffSize": "A", "testAccountInfo": "/serviceprovider/111.png", "tradingScenarios": "WECHAT_APPLET", "webSite": "http://www.test.com", "webSiteName": "测试网站", "webSitePath": "/serviceprovider/111.png", "wechatAppletName": "测试wechatApplet", "wechatAppletPath": "/serviceprovider/111.png" }, "configInfo": { "transferDomestic": { "certificateInfo": [ "/transfer/details/111.png" ], "feeAmount": "", "feeRate": "", "intervalAmountInfoList": [ { "feeAmount": "2", "feeRate": "3", "intervalAmount": "0", "rateType": "SYNTHETIC" }, { "feeAmount": "5", "feeRate": "6", "intervalAmount": "600", "rateType": "SYNTHETIC" } ], "other": "q", "purpose": "PROMOTION_FEE", "rateType": "INTERVALAMOUNT" } }, "contractInfo": { "receiverAddress": "大望路", "receiverName": "张三", "receiverPhone": "136****1154" }, "desireAuthInfo": { "legalPersonIdNo": "140***********2336", "legalPersonName": "测试人", "legalPersonPhoneNo": "13610241154" }, "extendedParameters": "sendActiveEmail:TRUE,sendExpressPayMsg:FALSE", "hmac": "mUOcaqBiF6s3XpQRxb7pCzHxGA==", "merchantId": "896666813", "notifyUrl": "https://qa-sdk.5upay.com/serviceprovider/declaration/notify", "operationType": "CREATE", "paymentProfiles": [ { "feeAmount": "1", "feeType": "SINGLE", "paymentMode": "B2C" }, { "feeAmount": "5", "feeType": "RATE", "paymentMode": "B2B" } ], "requestId": "1527746602492", "settlementProfile": { "cycleData": "4,5", "cycleType": "BYMONTH", "minAmount": "500", "reserveDays": "10", "settleMode": "REGULAR_SETTLE" } }

请求同步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
subMerchantId 子商户编号 由首信易返回的子商户编号
status 响应状态 SUCCESS 成功
FAILED 失败
ERROR 错误(此状态的返回参数见异常情况说明)
errorMessage 错误信息 错误信息
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

参数示例

{ "merchantId": "890000593", "requestId": "1527746602492", "subMerchantId": "890000593", "hmac": "mUOcaqBiF6s3XpQNnNk1Kf2c4XhEZ1ZfOJRGwo6YLcnSKnH/51cpEDFdZq4kx db2jddYCNbb52EzvGfonECapT+jcIex72hbgWinGtQz3xtj+iCyRESLwV0+aHoDqLd Zwj+9j4E7aDqUKNNzBy42MPG0guXqK0anfjkksaflksanlfsaknflawjfoafoasopw eiuwjdnciqnwuq+woincanneuvue/ndwnicnnwa+ncianvnwr+/M+D", "status": "SUCCESS" }

异步返回参数列表

参数名称 参数中文名称 参数说明
merchantId 商户编号 同请求参数
requestId 订单号 同请求参数
subMerchantReviewStatus 子商户审核状态 PROCESSING 审核中(ocr校验失败时返回该状态,子商户审核备注信息中可查看详情)
PASS 审核通过
NO_PASS 审核不通过
REFUSE 审核拒绝
ESIGN_PROCESS 待签约
ESIGN_PROCESSING 签约中
ESIGN_FAIL 签约失败(电子签签约状态)
ESIGN_SUCCESS 签约成功(电子签签约状态)
SUCCESS 入网完成
subMerchantReviewRemarks 子商户审核备注 审核备注
subMerchantId 子商户商编 子商户商编
electronicContractingUrl 电子签约链接 若签约方式为电子签约(自定义签约),则在子商户审核状态为“ESIGN_PROCESSING 签约中”时返回电子签约地址。
postReviewStatus 核查状态 INIT 初始化
SUCCESS 核查通过
FAIL 核查不通过
COMPLEMENT 核查补充
返回“核查补充”状态时,可通过“核查补充”接口或核查补充链接提交补充的材料,当触发入网后核查时, 会返回“核查状态”,核查不通过将影响交易
certificateSupplementUrl 核查补充链接 当异步返回参数中postReviewStatus“核查状态”为COMPLEMENT“核查补充”时,返回核查补充链接,入网商户可以通过该链接对需要补充的资质进行上传
postReviewRemark 核查备注 核查状态为“核查不通过“或“核查补充”时,返回该字段
hmac 参数签名 首信易生成的参数签名结果,验签过程请参考解密流程

参数示例

{ "hmac": "ts2WSc+ujkkMNMkqsqSbRJFFJt4tEGk/SXCJfbA0PuSRs2RaNOXm2e+cdpMmq 5C582BoAVXAmaw11LnyS2Y73oYYiMD4ZIVKD+8cSUo701NOYJPm1j06x5+cO9y2Uqi yF4yAOIJXEtn4LKvBKJ4b6tDfUVsz1rGqsuzFozPsdEJgC9gOJotzBDk8GHfoilCoI mhbxRUWwlO9FAMZVigd3O5YA1X+q8Zk/LlKNfPOGLsHULbOdnToASfQjv2SjkF0Ms8 /XpjJZSQYZcb0ECrPjVhR4B5/E7AWh1qRlKSkQ7v9cuJFj8GP6iDkNMolIzNXyQHY7 yKlmUIrdrTyQ92Oeg==", "merchantId": "890000***", "requestId": "1527746602492", "subMerchantReviewRemarks": "审核不通过", "subMerchantReviewStatus": "NO_PASS", "subMerchantId": "890002***" }