全部产品
云市场

聚合支付

更新时间:2020-01-02 18:50:10

产品介绍

面向支付场景,提供统一支付聚合支付能力,帮助商户降低支付费率,提升商户支付聚合支付能力。

准备工作:

申请入驻应用服务平台》》
入驻应用服务平台需要通过IoT团队审核,请联系IoT团队业务接口人。
创建项目管理》》
自定义选择自定义项目,项目中添加聚合支付能力
添加能力添加能力聚合支付属于增值服务,开通服务需要联系IoT团队进行审核,服务审核通过,即可调用相关接口。具体开发文档请参考聚合支付接口文档。

聚合支付服务

1、概述

聚合支付服务是为需要收款服务的商户提供的完整支付链路和订单查询的服务API,通过一套统一的API帮助商户接入微信支付和支付宝支付。

2、准备工作

开始对接聚合支付服务前,需要商户自行实现如下功能:

  • 入驻三方支付平台
    【支付宝】开通商户支付(生活号或小程序)
    【微信】开通公众号
  • 开发公众号/小程序,具有独立的云端应用;
  • 云端应用有独立的公网域名,并完成备案;

3、接入指南

接入步骤

接入步骤

AppKey和AppSecert

AppKey:API访问凭证编号,用于验证API接入API Gateway合法性;
AppSecret:与AppKey配套的验证秘钥,请妥善保管并确保不在网络中传输。

所有的聚合支付API均定义在IoT API网关上,AppKey和AppSecert是API网关的凭证访问,用户在接入时,可集成iot-api-gateway-client sdk,并配置AppKey和AppSecert。

在应用服务平台创建项目后,可进入项目,在项目开发态里获取到AppKey和AppSecert。appkey

支付流程

如图,聚合支付服务接入的商户需要完成静默授权、加载支付控件、处理回调结果三部分功能,以实现完整的支付流程。
支付流程

4、API说明

返回报文格式

参数 类型 备注
code Integer 业务返回码
message String 英文描述信息
localMessage String 中文描述信息
data 返回数据集,有下面四种情况:
- 无数据,这时没有data字段,表示接口的返回值中没有结果;
数据为对象类型,表示为JSONObject,具体定义要根据接口而定;
数据为数组类型,表示为JSONArray,表示结果是一系列值,值的类型要根据接口而定;
数据为值类型,表示为具体的封装类型,如String,Integer,Long,Byte,Double等。

业务返回码定义

错误码 错误信息 业务结果描述
200 success. 成功
500 service error. 服务端错误
20000 Request param [paramName] is error. 请求参数 [参数名] 错误。
20001 Image suffix is error. 图片后缀只支持jpg、jpeg、png。
20002 Image generate error. 图片转换失败。
20003 Image data save error. 图片数据保存失败。
20004 Merchant data operate error. 商户数据操作失败。
20005 Store data operate error. 门店数据操作失败。
20006 Merchant authen has passed. 商户已认证。
20007 Merchant is on authen. 商户认证中。
20008 Merchant authen error. 商户认证失败。
20009 Payment request error. 聚合支付请求错误。
20010 Payment business error. [聚合支付具体业务错误]。
20011 Payment request timeout. 聚合支付请求超时。

5、API定义

5.1 上传资质审核图片

功能描述

上传各类资质图片,商户入驻时作为入参。

接口定义

路径:/payment/image/upload
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
imageType String 必填 图片类型,见入参明细
imageData String 必填 图片Base64编码,见入参明细

入参明细

参数名 字段描述
imageType bankCard——银行卡;
idCard——身份证;
license——营业执照;
store——门店;
other——其他辅助证明。
imageData 图片最大不能超过1.35M,且转换Base64编码后,需要包含文件头(data:image/jpg;base64,),参数示例:
文件头——data:image/jpg;base64,
图片Base64——/9j/4AAQSkZJRgABAQEAYABgAD/2wBDAAMCAgMCAgMDAwMEAw
最终入参——data:image/jpg;base64,/9j/4AAQSkZJRgABAQEAYABgA/2wBDAAMCAgMCAgMDAwMEAw

出参data域(JSONObject)

参数名 字段类型 描述
resourceId String 图片资源id

业务示例

上传营业执照jpg格式图片。

请求示例

  1. {
  2. "imageType": "license",
  3. "imageData": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQEAYABgAD/2wBDAAMCAgMCAgMDAwMEAw"
  4. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "resourceId": "syrcvM40JEx9rJnh92paTNNdm8auKh3FBIiPKE13SzKpiFD8pkHNcDeNdVOTTQ3plZRk2bNYbvJXfOUl8fk4lp6wSVGXDlQ+vASSFEyN+XbK4pp4bqWrOTr59+q6mjtbp4WlbM+povzRpB+HoZTmNw=="
  7. }
  8. }
  9. 返回失败:
  10. {
  11. "code": 20002,
  12. "message": "Image generate error",
  13. "localizedMsg": "图片转换失败"
  14. }

5.2 商户入驻/重新入驻认证

功能描述

创建商户和门店信息,并进行认证审核/重新认证,只有首次认证失败后才可以重新认证。

接口定义

路径:/payment/merchant/entry
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
contactPhone String 必填 商户手机号
unityCategoryId Integer 必填 商户类目编号,子编号,见入参明细
name String 必填 法人真实姓名,最大长度32
idCardNo String 必填 法人身份证号
idCardFrontPhoto String 必填 身份证正面照资源id,最大长度255
idCardBackPhoto String 必填 身份证背面照资源id,最大长度255
bankCardNo String 必填 结算银行卡号
bankCardPhoto String 必填 银行卡正面照资源id,最大长度255
bankCellPhone String 必填 银行预留手机号
bankCode String 必填 银行编码,见入参明细
branchCode String 必填 支行编码,见入参明细
storeName String 必填 门店名称,最大长度19
storePhone String 必填 门店电话,最大长度16
provinceCode String 必填 省编码,见入参明细
cityCode String 必填 市编码,见入参明细
areaCode String 必填 区编码,见入参明细
streetAddress String 必填 详细地址,最大长度100
longitude String 必填 门店经度,精确到小数点后6位
latitude String 必填 门店纬度,精确到小数点后6位
licensePhoto String 必填 营业执照资源id,最大长度255
licenseName String 必填 营业执照名称,最大长度50
licenseId String 必填 营业执照编号,最大长度30
licenseTimeType Integer 必填 执照有效期类型,1正常,2长期
licenseTimeBegin String 非必填 执照起始有效期,执照有效期非长期时必填,格式yyyy-MM-dd
licenseTimeEnd String 非必填 执照终止有效期,执照有效期非长期时必填,格式yyyy-MM-dd
storeFrontPhoto String 必填 门头照资源id,最大长度255
storeEnvPhoto String 必填 门店环境照资源id,最大长度255
storeCashPhoto String 必填 收银台照资源id,最大长度255
remark String 非必填 备注,最大长度500
merchantCode String 非必填 系统商户号,重新入驻时必填,最大长度60
storeCode String 非必填 系统门店号,重新入驻时必填,最大长度60

入参明细

参数名 字段描述
unityCategoryId 详见附录6.1。
bankCode 详见附录6.2。
unionpayCode 详见附录6.2。
provinceCode 详见附录6.3。
cityCode 详见附录6.3。
areaCode 详见附录6.3。

出参data域(JSONObject)

参数名 字段类型 描述
merchantCode String 系统商户号
merchantStatus Integer 商户认证状态,0未认证,1认证中,2认证成功,3认证失败
storeCode String 系统门店号
storeStatus Integer 门店审核状态,1待审核,2审核通过,3审核驳回
signSecret String 回调验签秘钥,首次入驻时返回,请妥善保存

业务示例

商户首次入驻。

请求示例

  1. {
  2. "contactPhone": "13505069831",
  3. "unityCategoryId": 58,
  4. "name": "张三",
  5. "idCardNo": "110101198905102697",
  6. "idCardFrontPhoto": "YQp2FRgR3D3hpQGV2KtBEDl88cqmLMs+LHgcuYZb4xc=",
  7. "idCardBackPhoto": "Bbc39u5S9x3hpQGBk30xEDl88cqmLMs+LHgcuYZb4xc=",
  8. "bankCardNo": "6666080820191127",
  9. "bankCardPhoto": "Xbc39u5S9x3hpQgbk30xEDl90cqmLxC=",
  10. "bankCellPhone": "13505069831",
  11. "bankCode": "105100000017",
  12. "branchCode": "1356990812",
  13. "storeName": "某某店",
  14. "storePhone": "15911789803",
  15. "provinceCode": "120000",
  16. "cityCode": "120100",
  17. "areaCode": "120001",
  18. "streetAddress": "某街道某楼某层200号",
  19. "longitude": "117.208122",
  20. "latitude": "39.118896",
  21. "licensePhoto": "1234567890",
  22. "licenseName": "某营业执照",
  23. "licenseId": "9876543210",
  24. "licenseTimeType": 1,
  25. "licenseTimeBegin": "2019-11-27",
  26. "licenseTimeEnd": "2030-11-27",
  27. "storeFrontPhoto": "Sbc50u5S9x3hpQgck303EDl80cqmLxa=",
  28. "storeEnvPhoto": "Ebc19u5S9x3hpQ3bk30xEDl90cqmLcD=",
  29. "storeCashPhoto": "Cbc0xu5S9x3hpkglk30xEDl10c1mKOv=",
  30. "remark": "备注",
  31. "merchantCode": "",
  32. "storeCode": ""
  33. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  7. "merchantStatus": 2,
  8. "storeCode": "df152383d40842b0814346cc88cfd1b4",
  9. "storeStatus": 2,
  10. "signSecret": "ek15f356dlc842b991r346c5d8cfclp1"
  11. }
  12. }
  13. 返回失败:
  14. {
  15. "code": 20008,
  16. "message": "Merchant authen error",
  17. "localizedMsg": "商户认证失败"
  18. }

5.3 添加门店信息

功能描述

创建商户下的新门店。

接口定义

路径:/payment/store/add
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
storeName String 必填 门店名称,最大长度19
storePhone String 必填 门店电话,最大长度16
provinceCode String 必填 省编码,见入参明细
cityCode String 必填 市编码,见入参明细
areaCode String 必填 区编码,见入参明细
streetAddress String 必填 详细地址,最大长度100
longitude String 必填 门店经度,精确到小数点后6位
latitude String 必填 门店纬度,精确到小数点后6位
licensePhoto String 必填 营业执照资源id,最大长度255
licenseName String 必填 营业执照名称,最大长度50
licenseId String 必填 营业执照编号,最大长度30
licenseTimeType Integer 必填 执照有效期类型,1正常,2长期
licenseTimeBegin String 非必填 执照起始有效期,执照有效期非长期时必填,格式yyyy-MM-dd
licenseTimeEnd String 非必填 执照终止有效期,执照有效期非长期时必填,格式yyyy-MM-dd
storeFrontPhoto String 必填 门头照资源id,最大长度255
storeEnvPhoto String 必填 门店环境照资源id,最大长度255
storeCashPhoto String 必填 收银台照资源id,最大长度255
remark String 非必填 备注,最大长度500
merchantCode String 必填 系统商户号,重新入驻时必填,最大长度60

入参明细

参数名 字段描述
provinceCode 详见附录6.3。
cityCode 详见附录6.3。
areaCode 详见附录6.3。

出参data域(String)

参数名 字段类型 描述
storeCode String 系统门店号
storeStatus Integer 门店审核状态,1待审核,2审核通过,3审核驳回

业务示例

创建系统号为8e2e8d41f4604878b413fc588333f068的商户下的新门店。

请求示例

  1. {
  2. "storeName": "某某店",
  3. "storePhone": "15911789803",
  4. "provinceCode": "120000",
  5. "cityCode": "120100",
  6. "areaCode": "120001",
  7. "streetAddress": "某街道某楼某层200号",
  8. "longitude": "117.208122",
  9. "latitude": "39.118896",
  10. "licensePhoto": "1234567890",
  11. "licenseName": "某营业执照",
  12. "licenseId": "9876543210",
  13. "licenseTimeType": 1,
  14. "licenseTimeBegin": "2019-11-27",
  15. "licenseTimeEnd": "2030-11-27",
  16. "storeFrontPhoto": "Sbc50u5S9x3hpQgck303EDl80cqmLxa=",
  17. "storeEnvPhoto": "Ebc19u5S9x3hpQ3bk30xEDl90cqmLcD=",
  18. "storeCashPhoto": "Cbc0xu5S9x3hpkglk30xEDl10c1mKOv=",
  19. "remark": "备注",
  20. "merchantCode": "8e2e8d41f4604878b413fc588333f068"
  21. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "storeCode": "df152383d40842b0814346cc88cfd1b4",
  7. "storeStatus": 1
  8. }
  9. }
  10. 返回失败:
  11. {
  12. "code": 20005,
  13. "message": "Store data operate error",
  14. "localizedMsg": "商户数据操作失败"
  15. }

5.4 修改门店信息

功能描述

修改门店信息,会重置已审核的门店状态。入驻时,若商户认证通过,门店审核失败,此接口可重置门店审核。

接口定义

路径:/payment/store/update
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
storeName String 必填 门店名称,最大长度19
storePhone String 必填 门店电话,最大长度16
provinceCode String 必填 省编码,见入参明细
cityCode String 必填 市编码,见入参明细
areaCode String 必填 区编码,见入参明细
streetAddress String 必填 详细地址,最大长度100
longitude String 必填 门店经度,精确到小数点后6位
latitude String 必填 门店纬度,精确到小数点后6位
licensePhoto String 必填 营业执照资源id,最大长度255
licenseName String 必填 营业执照名称,最大长度50
licenseId String 必填 营业执照编号,最大长度30
licenseTimeType Integer 必填 执照有效期类型,1正常,2长期
licenseTimeBegin String 非必填 执照起始有效期,执照有效期非长期时必填,格式yyyy-MM-dd
licenseTimeEnd String 非必填 执照终止有效期,执照有效期非长期时必填,格式yyyy-MM-dd
storeFrontPhoto String 必填 门头照资源id,最大长度255
storeEnvPhoto String 必填 门店环境照资源id,最大长度255
storeCashPhoto String 必填 收银台照资源id,最大长度255
remark String 非必填 备注,最大长度500
merchantCode String 必填 系统商户号,重新入驻时必填,最大长度60
storeCode String 必填 系统门店号,重新入驻时必填,最大长度60

入参明细

参数名 字段描述
provinceCode 详见附录6.3。
cityCode 详见附录6.3。
areaCode 详见附录6.3。

出参data域(String)

出参字符串
修改门店后将进行下线审核流程, 可通过查询门店信息接口获取审核结果

业务示例

修改门店信息,重置门店审核。

请求示例

  1. {
  2. "storeName": "某某店",
  3. "storePhone": "15911789803",
  4. "provinceCode": "120000",
  5. "cityCode": "120100",
  6. "areaCode": "120001",
  7. "streetAddress": "某街道某楼某层200号",
  8. "longitude": "117.208122",
  9. "latitude": "39.118896",
  10. "licensePhoto": "1234567890",
  11. "licenseName": "某营业执照",
  12. "licenseId": "9876543210",
  13. "licenseTimeType": 1,
  14. "licenseTimeBegin": "2019-11-27",
  15. "licenseTimeEnd": "2030-11-27",
  16. "storeFrontPhoto": "Sbc50u5S9x3hpQgck303EDl80cqmLxa=",
  17. "storeEnvPhoto": "Ebc19u5S9x3hpQ3bk30xEDl90cqmLcD=",
  18. "storeCashPhoto": "Cbc0xu5S9x3hpkglk30xEDl10c1mKOv=",
  19. "remark": "备注",
  20. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  21. "storeCode": "df152383d40842b0814346cc88cfd1b4"
  22. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": "修改门店后将进行下线审核流程, 可通过查询门店信息接口获取审核结果"
  6. }
  7. 返回失败:
  8. {
  9. "code": 20005,
  10. "message": "Store data operate error",
  11. "localizedMsg": "商户数据操作失败"
  12. }

5.5 查询商户门店审核状态

功能描述

查询商户认证状态和门店审核状态。

接口定义

路径:/payment/store/status/get
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
merchantCode String 必填 系统商户号,重新入驻时必填,最大长度60
storeCode String 必填 系统门店号,重新入驻时必填,最大长度60

入参明细

参数名 字段描述
—-

出参data域(JSONObject)

参数名 字段类型 描述
merchantCode String 系统商户号
merchantStatus Integer 商户认证状态,0未认证,1认证中,2认证成功,3认证失败
storeCode String 系统门店号
storeStatus Integer 门店审核状态,1待审核,2审核通过,3审核驳回

业务示例

查询门店审核状态。

请求示例

  1. {
  2. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  3. "storeCode": "df152383d40842b0814346cc88cfd1b4"
  4. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  7. "merchantStatus": 2,
  8. "storeCode": "df152383d40842b0814346cc88cfd1b4",
  9. "storeStatus": 2
  10. }
  11. }
  12. 返回失败:
  13. {
  14. "code": 20008,
  15. "message": "Merchant authen error",
  16. "localizedMsg": "商户认证失败"
  17. }

5.6 统一下单

功能描述

调用支付宝或微信生成预支付订单。

接口定义

路径:/payment/order/create
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
merchantCode String 必填 系统商户号,最大长度60
storeCode String 必填 系统门店号,最大长度60
appId String 非必填 公众号id,微信支付时必填
outUserId String 必填 用户标识,支付宝userid或微信openid
payType String 必填 支付方式,alipay支付宝,wxpay微信
totalPrice Float 必填 支付总额,最少0.01,精确到0.01
notifyUrl String 必填 支付结果回调地址,最大长度128
deviceNo String 非必填 设备号,用于分类统计商户门店的订单信息,最大长度32

入参明细

参数名 字段描述
appId 微信公众号appId,所以payType是wxpay时,必须传入appId
notifyUrl 支付回调地址,由于统一下单时并未实际支付,同步返回的只有下单结果和预支付id。后续跳转到支付宝或微信完成支付后,会将订单支付结果通过回调地址返回。
回调方式:Http Post(ContentType=application/json),订单支付结果数据以json格式存在RequestBody中,所以需要商户拥有自己的应用,并对公网开放http接口。
outUserId 用户标识,支付宝或微信通过静默授权获取的实际支付C端用户的唯一标识,获取方式详见支付宝或微信的接入文档
deviceNo 所有订单归属在商户的门店下,不同设备号可用于分类统计订单数量金额等信息。

出参data域(JSONObject)

参数名 字段类型 描述
outOrderId String 系统订单号
prePayId String 预支付凭证(微信预支付订单号、支付宝交易号)

业务示例

调用微信支付方式的统一下单。

请求示例

  1. {
  2. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  3. "storeCode": "df152383d40842b0814346cc88cfd1b4",
  4. "appId": "wxpd91e260e0fxz409",
  5. "outUserId": "ebxC_e3wW8cP3jFtbZhqLEurK3Ls",
  6. "payType": "wxpay",
  7. "totalPrice": 0.01,
  8. "notifyUrl": "http://callback.com/receivePayResult",
  9. "deviceNo": "device.001"
  10. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "outOrderId": "6cd2659b01ac43a7a10d3ca2901a17d7",
  7. "prePayId": "wx02105928709909ba97dce9ab1794326100"
  8. }
  9. }
  10. 返回失败:
  11. {
  12. "code": 20102,
  13. "message": "Store code not found",
  14. "localizedMsg": "聚合支付门店码错误"
  15. }

异步回调验签

统一下单后同步返回的prePayId,商户可用于调起支付宝和微信支付控件,支付成功,平台方会主动发起回调到用户的notifyUrl(post请求,ContentType=application/x-www-form-urlencoded)。
商户接收到回调后,需要同步应答,返回“success”,否则平台方将会重发,最多16次。需要商户需要使用验签代码对回调参数进行校验。校验通过后,方可更新自身的业务数据。

回调参数明细(平台方回调,注意参数格式为下划线式)

参数名 字段类型 描述
merchant_order_sn String 系统订单号
order_status String 订单状态,SUCCESS
pay_type String 支付方式,alipay支付宝,wxpay微信
total_amount Float 支付总额,最少0.01,精确到0.01
user_id String 用户标识,支付宝userid或微信openid
finish_time String 支付完成时间,格式为yyyyMMddHHmmss。
device_no String 设备号,用于分类统计商户门店的订单信息,最大长度32

验签代码

OrderCallbackSignUtil.java

回调报文示例

  1. {
  2. "merchant_order_sn":"46679aba41fe488880dd4b2bedc093d3",
  3. "order_status":"SUCCESS",
  4. "pay_type":"wxpay",
  5. "total_amount":0.01,
  6. "user_id":"ebxC_e3wW8cP3jFtbZhqLEurK3Ls",
  7. "finish_time":"20191201152030",
  8. "device_no":"device.001"
  9. }

5.7 订单查询

功能描述

查询统一下单订单信息。

接口定义

路径:/payment/order/query
版本:1.0.0

入参

参数名 字段类型 是否必填 描述
merchantCode String 必填 系统商户号,最大长度60
outOrderId String 必填 系统订单号

入参明细

参数名 字段描述
outOrderId 统一下单同步返回的系统订单号。

出参data域(JSONObject)

参数名 字段类型 描述
outOrderId String 系统订单号。
orderStatus String USERPAYING—用户支付中;
SUCCESS—支付成功;
REVOKED—已撤销;
CLOSED—已关闭;
REVOKING—撤销中。
payType String 支付方式,wxpay 微信,alipay 支付宝。
totalPrice Float 订单金额,精确到0.01。
storeCode String 系统门店号。
outUserId String 付款用户id。
finishTime String 支付完成时间,格式为yyyyMMddHHmmss。

业务示例

查询订单信息。

请求示例

  1. {
  2. "merchantCode": "8e2e8d41f4604878b413fc588333f068",
  3. "outOrderId": "b87d1040c7494caea6e0836859473825"
  4. }

返回示例

  1. 返回成功:
  2. {
  3. "code": 200,
  4. "message": "success",
  5. "data": {
  6. "outOrderId": "b87d1040c7494caea6e0836859473825",
  7. "orderStatus": "SUCCESS",
  8. "payType": "wxpay",
  9. "totalPrice": 0.01,
  10. "storeCode": "df152383d40842b0814346cc88cfd1b4",
  11. "outUserId": "ebxC_e3wW8cP3jFtbZhqLEurK3Ls",
  12. "finishTime": "20191201153023"
  13. }
  14. }
  15. 返回失败:
  16. {
  17. "code": 20100,
  18. "message": "Order not found",
  19. "localizedMsg": "聚合支付订单未找到"
  20. }

6、附录

6.1商户类目编号

行业类目编号

6.2银行编码和支行编码

银行编码支行编码

6.3省市区编码

省市区编码