全部产品
云市场

聚合支付

更新时间:2019-12-03 16:59:20

服务介绍

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

聚合支付商户接口

一、概述

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

二、调用方法

注意:

  1. 在应用服务平台申请appKey,开通对应的服务接口;
  2. 获取appKey和appSecret(请妥善保管)后,需要使用appKey和appSecret访问;
  3. 接口仅支持https协议,以post请求访问;
  4. 调用试例地址: https://github.com/aliyun/iotx-api-gateway-client

三、准备工作

开始对接聚合支付服务前,需要商户自行实现如下功能:
1.具备公网备案域名;
2.有独立的云端应用支持;
3.接入支付宝生活号和微信公众号。

appKey和appSecret

通过iot-api-gateway-client访问时的准入参数,可以在应用服务平台,项目内的开发态进行查看,定义如下:1.appKey:API接口验证序号,用于验证API接入API Gateway合法性;2.appSecret:与appKey配套的验证秘钥,请妥善保管并确保不在网络中传输。

支付宝生活号

接入文档:https://docs.alipay.com/fw/guide

微信公众号

接入文档:https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html

支付场景流程图

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

四、错误码

通用返回码

错误码 错误信息 错误描述
200 success. 成功
400 request error. 请求错误
401 request auth error. 请求认证错误
403 request forbidden. 请求被禁止
404 service not found. 服务未找到
429 too many requests. 太多请求
460 request parameter error. 请求参数错误
500 service error. 服务端错误
503 service not available. 服务不可用

业务错误码

错误码 错误信息 业务结果描述
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. 聚合支付请求超时。

五、通用定义

通用入参

准入参数

名称 类型 备注
appKey String API接入序号
appSecret String API接入秘钥

通用返回

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

六、API接口定义

1.上传资质审核图片文件

功能描述

上传各类资质图片文件,后续需要审核时作为入参。

接口定义

  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,/9j/4AAQSkZJRgABAQEAYABgAD/2wBDAAMCAgMCAgMDAwMEAw。

出参data域(JSONObject)

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

示例

上传营业执照图片。

请求示例

  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. }

2.商户入驻/重新入驻认证

功能描述

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

接口定义

  1. /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 详见[附录1]
bankCode 详见[附录2]
unionpayCode
provinceCode 详见[附录3]
cityCode
areaCode

出参data域(JSONObject)

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

示例

商户入驻。

请求示例

  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. }
  11. }
  12. 返回失败:
  13. {
  14. "code": 20008,
  15. "message": "Merchant authen error",
  16. "localizedMsg": "商户认证失败"
  17. }

3.修改门店信息

功能描述

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

接口定义

  1. /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 详见[附录3]。
cityCode
areaCode

出参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. }

4.查询商户门店状态

功能描述

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

接口定义

  1. /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.统一下单

功能描述

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

接口定义

  1. /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. }

6.订单查询

功能描述

查询统一支付订单信息。

接口定义

  1. /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. }

七、附录

1.商户类目编号

行业类目编号

2.银行编码和支行编码

银行编码支行编码

3.省市区编码

省市区编码