帮助与文档

> >

ShopSDK对接开发者自有支付系统开发指南

1、引言

1.1 文档概述

本文件描述Mob ShopSDK针对开发者自有支付系统提供的解决方案(即您可以使用您的自有支付系统接入shopSDK,支付系统对接的财务对账系统等均可以不做修改,方便您更好的接入ShopSDK)。文档分别从签名、接口、注意事项等方面详细介绍了Mob ShopSDK的工作方式和开发过程,可以帮助开发人员快速入门并掌握开发技能,同时也可以作为日后接口参数以及参数类型的速查手册。

1.2 阅读对象

供使用您自有的支付系统接入ShopSDK的技术或业务人员参考和查询。

 

1.3 业务术语

术语 示例 说明
appkey 1900000109 开发者在MOB服务中唯一标识
mobsign 9ba2380ad9b2aacb96

bca514eda27ac9

为保证通讯不被篡改,当做签名使用
appsecret appkey的关联信息,用作计算签名使用
金额 100000 金额,默认为RMB,以分为单位。1000表示RMB10.00

2、方案概述

2.1 行业背景

在电子商务中,商家、买家、中间服务方是交易活动中的三个环节。买家选购商品下发订单,商家确认订单,买家通过支付服务方向商家支付货款,商家发货履行订单。针对于开发者自有支付服务,EtradeSdk提供接口和开发者自有支付服务进行对接,为开发者提供更友好体验.

接口介绍

接口名 请求URL 功能说明 结果说明
对接自有支付系统订单支付状态变更接口

 

http://openapi.shop.mob.com/thirdparty

/ertrance/updateOrderStatus

调用该接口时指定订单信息,支付金额,支付ticket等,完成开发者服务通知Mob支付结果 返回结果中status返回200,message返回SUCCESS,表示mob服务响应成功
对接自有支付系统订单查询接口  http://openapi.shop.mob.com/thirdparty/

ertrance/queryOrderDetail

调用接口时指定订单id,appkey,查询该订单支付金额 返回结果中会携带订单id,该订单实际支付金额,以及订单总金额。
对接自有支付系统退款进度状态变更接口 http://openapi.shop.mob.com//thirdparty/

ertrance/updateRefundStatus

调用接口时指定退款商品id,退款金额,退款状态通知Mob退款结果 返回结果中status返回200,message返回SUCCESS,表示mob服务响应成功
对接自有支付系统退款商品查询接口 http://openapi.shop.mob.com/

thirdparty/ertrance/queryRefundList

调用接口时可以指定条件查询退款订单信息 返回结果中会携带退款商品id,退款金额以及关联的订单id,订单金额

2.2 加解密流程图

2.3 业务流程图

3、数据格式

3.1 请求方式

采用HTTP标准的POST协议,为了保证接收方接收数据正确,传递的参数如果存在特殊字符(如&、=等)需要进行URL Encode。

3.2 响应格式

直接以简单字符串作为数据内容,一般用于后台通知模式的接口反馈,表示处理是否成功。

返回结果 结果说明
status:200 表示响应成功
message:SUCCESS 表示处理成功
data: 响应业务数据

 

4、数字签名

为了保证数据传输过程中的数据真实性和完整性,我们需要对数据进行数字签名,在接收签名数据之后进行签名校验。

数字签名有两个步骤,先按一定规则拼接要签名的原始串,再选择具体的算法和密钥计算出签名结果。

一般失败的结果不签名。

4.1 签名原始串

  • 所有参数按照字段名的ascii码从小到大排序后使用QueryString的格式(即key1=value1&key2=value2…)拼接而成
  • 参数最后一位为appsecret:值(该值为开发者appkey关联信息)拼接前面参数,使用MD5加密,生产签名

3、签名原始串中,字段名和字段值都采用原始值,不进行URL Encode。

 

举例:

调用某个接口,接口有如下字段:

partner、total_fee、desc、attach

实际调用接口时,各字段的值:

partner=1900000109,total_fee=1,desc=a&b,attach=,test=1

正确的签名原始串是:

desc=a&b&partner=1900000109&test=1&total_fee=1

常见的错误有:

desc=a%26b&partner=1900000109&test=1&total_fee=1

desc=a&b&partner=1900000109&total_fee=1

attach=&desc=a&b&partner=1900000109&test=1&total_fee=1

partner=1900000109&total_fee=1&desc=a&b&test=1

 

4.2 签名算法

目前暂只支持MD5签名

MD5签名

MD5 是一种摘要生成算法,通过在签名原始串后加上商户通信密钥的内容,进行MD5运算,形成的摘要字符串即为签名结果。为了方便比较,签名结果统一转换为大写字符。

注意:签名时将字符串转化成字节流时指定的编码字符集应为utf-8

MD5签名计算公式:

sign = Md5(原字符串& appsecret =开发者appsecret). toUpperCase

如:

签名原始串是: partner=1900000109&total_fee=1

开发者appsecret是:8934e7d15453e97507ef794cf7b0519d

签名的结果为:

sign=md5(input_charset=GBK&partner=1900000109&total_fee=1&appsecret=8934e7d15453e97507ef794cf7b0519d)= 4C513CB879523CA9D717EEA7819DEB0C

5、接口

5.1 对接自有支付系统订单支付状态变更接口

5.1.1 业务功能

订单支付状态变更

5.1.2 请求参数列表

请求url:http://openapi.shop.mob.com/thirdparty/ertrance/updateOrderStatus

通过post请求

字段名 变量名 必填 类型 说明
请求头
appkey appkey Y String Mob appkey
签名 mobsign Y String 参照4计算
业务参数
订单唯一标识 orderId Y Long
订单总金额(以分为单位) totalMoney Y Integer
支付金额(以分为单位) paidMoney Y Integer
订单支付状态,1成功,2失败,3取消 payStatus

 

Y Integer
mob appkey appkey Y String
支付Ticket payTicket Y String

JSON格式:

 

{
“orderId”:90892555608600576,
“appkey”:”221a0c04f52d4″,
“totalMoney”:1000,
“payTicket”:”123a”,
“paidMoney”:800,
“payStatus”:1
}

5.1.3   返回结果参数列表

数据按json的格式实时返回

字段名 变量名 必填 类型 说明
响应头
签名 mobsign Y String 参照4计算
业务参数
参照3.2

 

成功示例:

{

“status”: 200,

“message”: “”,

“data”: “”

}

 

5.2     对接自有支付系统订单查询接口

5.2.1   业务功能

订单查询接口

5.2.2   请求参数列表

请求url: http://openapi.shop.mob.com/thirdparty/ertrance/queryOrderDetail

通过post请求

字段名 变量名 必填 类型 说明
请求头
appkey appkey Y String Mob appkey
签名 mobsign Y String 参照4计算
业务参数
订单id orderId Y Long
appkey appkey Y String

JSON格式:

{

“orderId”:90892555608600576,
“appkey”:”221a0c04f52d4″
}

 

5.2.3   返回结果参数列表

字段名 变量名 必填 类型 说明
响应头
签名 mobsign Y String 参照4计算
业务参数
订单唯一标识 orderId Y Long
支付金额(以分为单位 paidMoney Y Integer
订单金额(以分为单位) totalMoney Y Integer

成功示例:

{
“status”: 200,
“message”: “”,
“data”: {
“orderId”: 2,
“paidMoney”: 201,
“totalMoney”: 1000
}
}

5.3     对接自有支付系统退款商品查询接口

5.3.1   业务功能

退款商品查询接口

5.3.2   请求参数列表

请求url:http://openapi.shop.mob.com/thirdparty/ertrance/queryRefundList

通过post请求

字段名 变量名 必填 类型 说明
请求头
appkey appkey Y String Mob appkey
签名 mobsign Y String 参照4计算
业务参数
appkey appkey Y String
订单开始时间 orderBeginAt N Date
订单结束时间 orderEndAt N Date
订单号 orderId N Long
商品名称(可做模糊查询) productName N String
退款申请时间Begin refundApplyBeginDate N Date
退款申请时间End refundApplyEndDate N Date
用户ID(第三方系统用户ID) buyerId N String
页码 pageIndex N Integer
数量 pageSize N Integer

JSON格式:

{
“appkey”:”221a0c04f52d4″,
“orderBeginAt”:”2017-11-28 11:50:13″,
“orderEndAt”:”2017-12-28 11:50:13″,
“refundApplyBeginDate”:”2017-11-2811:50:13″,
“refundApplyEndDate”:”2017-12-28 11:50:13″,
“orderId”:12346567512,
“productName”:”毛巾”,
“buyerId”:”1245233A”,
“pageIndex”:1,
“pageSize”:10
}

5.3.3 返回结果参数列表

字段名 变量名 必填 类型 说明
响应头
签名 mobsign Y String 参照4计算
业务参数
退款商品唯一标识 refundCommodityId Y Long
退款金额(以分为单位) refundFee Y Integer
订单唯一标识 orderId Y Long
订单支付金额(以分为单位 orderPaidMoney Y Integer

成功示例:

{
“status”: 200,
“message”: “”,
“data”: {
“pageIndex”: 1,
“count”: 1,
“list”: [
{
“refundCommodityId”: “98830451051405312”,
“refundFee”: 100,
“orderPaidMoney”: 100,
“orderId”: “99140624904790016”
}
]
}
}

5.4 对接自有支付退款状态变更接口

5.4.1 业务功能

对接自有支付系统退款进度状态变更。

5.4.2 请求参数列表

请求url:http://openapi.shop.mob.com//thirdparty/ertrance/updateRefundStatus

通过post请求

字段名 变量名 必填 类型 说明
请求头
appkey appkey Y String Mob appkey
签名 mobsign Y String 参照4计算
业务参数
退款商品集合 refundList Y List
退款商品唯一标识 refundCommodityId Y Long
实际退款金额以分为单位 refundFee Y Integer
退款状态 0表示退款成功,1表示退款失败 status Y Integer
appkey appkey Y String

JSON格式:

{

“appkey”:”221a0c04f52d4″,
“refundList”:
[
{
“refundCommodityId”:90892555608600576,
“refundFee”:100,
“status”:0
}
]
}

 

5.4.3 返回结果参数列表

数据按json的格式实时返回

字段名 变量名 必填 类型 说明
响应头
签名 mobsign Y String 参照4计算
业务参数
参照3.2

成功示例:

{

“status”: 200,

“message”: “SUUCCESS”,

“data”: “”

}

 

 

6、注意事项

  • 所有涉及到金额的单位都是分,最小的单位是1分,不能有小数出现
  • 请求头中必须携带appkey以及mobsign信息
  • RSA加密算法,MD5签名算法详细见附件

加密方法

  • 在对接前需前往MOB后台管理页面获取公钥,输入您的服务器外网IP

0 0

相关文档