目录
4.1 接口返回码retcode说明
接口版本号(version)为空或者版本号等于11：
SUCCESS-请求成功
FAIL-请求或前端处理失败，具体看retmsg
接口版本号(version)大于11：
SUCCESS-请求成功
PARAMERR-请求参数错误
SIGNAUTHERR-签名或者api权限不足
FAIL-其他请求或前端处理失败，具体看retmsg
SYSTEMERR-系统异常，对于实时类交易（例如被扫交易），建议进行查询
4.2 交易返回码trxstatus说明
0000：交易成功
1001：交易不存在
2008或者2000 : 交易处理中,请查询交易,如果是实时交易(例如刷卡支付,交易撤销,退货),建议每隔一段时间(10秒)查询交易
3开头的错误码代表交易失败
3888-流水号重复
3889-交易控制失败，具体原因看errmsg
3099-渠道商户错误
3014-交易金额小于应收手续费
3031-校验实名信息失败
3088-交易未支付(在查询时间区间内未成功支付,如已影响资金24小时内会做差错退款处理)
3089-撤销异常,如已影响资金24小时内会做差错退款处理
3045-其他错误，具体原因看errmsg
3050-交易已被撤销
3999-其他错误，具体原因看errmsg
其他3开头的错误码代表交易失败,具体原因请读取errmsg
4.3 交易类型
|
交易类型 |
注释 |
|
VSP501 |
微信支付 |
|
VSP502 |
微信支付撤销 |
|
VSP503 |
微信支付退款 |
|
VSP511 |
支付宝支付 |
|
VSP512 |
支付宝支付撤销 |
|
VSP513 |
支付宝支付退款 |
|
VSP541 |
扫码支付 |
|
VSP542 |
扫码撤销 |
|
VSP543 |
扫码退货 |
|
VSP551 |
银联扫码支付 |
|
VSP552 |
银联扫码撤销 |
|
VSP553 |
银联扫码退货 |
|
VSP611 |
数字货币支付 |
|
VSP612 |
数字货币撤销 |
|
VSP613 |
数字货币退货 |
|
300002 |
充值 |
|
DMM999 |
全抵扣 |
|
VSP681 |
微信订单预消费 |
|
VSP682 |
微信订单退款 |
|
VSP683 |
微信订单完成 |
|
VSP684 |
微信订单完成退款 |
4.4 支付渠道优惠信息填写规范（benefitdetail字段）
微信单品优惠填写规范
需填写goods_tag和benefitdetail字段，其中benefitdetail是包含了以下字段的json字符串：
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
cost_price |
订单原价 |
int |
是 |
单位:分 跟trxamt一致 |
|
receipt_id |
商品小票ID |
String(32) |
是 |
|
|
goods_detail |
单品列表 |
List<GoodDetail> |
否 |
|
GoodDetail的字段如下:
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
goods_id |
商品编码 |
String(32) |
否 |
由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 |
|
wxpay_goods_id |
微信侧商品编码 |
String(32) |
是 |
微信支付定义的统一商品编号（没有可不传） |
|
goods_name |
商品名称 |
String(256) |
是 |
商品的实际名称 |
|
quantity |
商品数量 |
int |
否 |
用户购买的数量 |
|
price |
商品单价 |
int |
否 |
单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的纸质优惠券100-50，则活动商品的单价应为原单价-50) |
单品优惠数据样例:
benefitdetail={"goods_detail":[{"price":10,"goods_id":"cola50","goods_name":"cola","quantity":10}],"cost_price":120}&goods_tag=laoguo
支付宝智慧门店填写规范
支付宝智慧门店需要进行报备，具体咨询业务经理。（只支持主扫和被扫）
需填写chnlstoreid和benefitdetail字段；chnlstoreid为该商户在支付宝的商户门店号；benefitdetail是优惠商品详情的列表。
其中商品详情字段如下：
|
参数 |
参数名称 |
数据类型 |
可空 |
示例 |
|
goods_id |
商品的编码 |
String(32) |
否 |
apple-01 |
|
goods_name |
商品名称 |
String(256) |
否 |
ipad |
|
quantity |
商品数量 |
Number(10) |
否 |
1 |
|
price |
商品单价，单位为元 |
Price(9) |
否 |
2000 |
|
goods_category |
商品类目 |
String(24) |
可 |
34533238 |
|
categories_tree |
商品类目树，从商品类目根节点到叶子节点类目id组成，类目id值使用|分割 |
String(128) |
可 |
123123123|1212313|12313123 |
|
body |
商品描述信息 |
String(1000) |
可 |
特价手机 |
|
show_url |
商品的展示地址 |
String(400) |
可 |
http://www.alipay.com/xxxx.jpg |
样例数据:
benefitdetail=[{"price":2,"goods_id":"900820400100","goods_name":"900820400iphonex ","quantity":1}]&chnlstoreid=240610147@020012003
银联云闪付单品优惠填写规范
注意：
1.仅支持被扫交易，即4.2统一扫码接口
2.统一扫码交易同步返回在渠道信息（chnldata ）返回银联优惠信息(couponInfo).
3.银联云闪付单品优惠交易退货不支持部分退款，并且需要在退款接口上送原交易的优惠信息，见4.4退款接口
benefitdetail是包含了以下字段的json字符串：
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
orderInfo |
订单明细内容 |
UnOrderInfo |
否 |
如订单标题、订单描述等 |
|
goodsInfo |
商品明细内容 |
List<UnGoodDetail> |
否 |
|
其中UnOrderInfo包含字段如下:
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
title |
商品编码 |
String(100) |
否 |
|
|
description |
订单描述 |
String(200) |
否 |
|
|
dctAmount |
可优惠金额 |
int |
是 |
当前订单可以参与优惠计算的金额 |
|
addnInfo |
附加信息 |
String(100) |
是 |
用户自定义 |
其中UnGoodDetail包含字段如下:
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
id |
商品编码 |
String(32) |
否 |
|
|
name |
商品名称 |
String(256) |
否 |
商品的实际名称 |
|
quantity |
商品数量 |
int |
否 |
用户购买的数量 |
|
price |
商品单价 |
int |
否 |
单位为：分 |
|
category |
商品类目 |
String(24) |
是 |
|
|
addnInfo |
附加信息 |
String(100) |
是 |
用户自定义 |
填写样例:
benefitdetail={"goodsInfo":[{"id":"testsp000005","price":"600","name":"商品 1","quantity":"2"},{"id":"testsp000006","price":"500","name":"商品 2","quantity":"1"}],"orderInfo":{"title":"日用品","dctAmount":"1900","addnInfo":"日屈臣氏(人民广场)店"}}
交易成功返回优惠信息字段:
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
id |
项目编号 |
String(40) |
否 |
票券编号、活动编号等，格式自定义 |
|
type |
项目类型 |
String(4) |
否 |
|
|
offstAmt |
抵消交易金额 |
int |
否 |
单位为：分 |
|
spnsrId |
出资方 |
String(20) |
否 |
|
|
desc |
项目简称 |
String(60) |
否 |
优惠活动简称，可用于展示、打单等 |
|
addnInfo |
附加信息 |
String(100) |
是 |
用户自定义 |
响应样例:
chnldata ={"couponInfo":[{"id":"2112019092900801","desc":"银联单品测试联调-折后一口价","addnInfo":"小票打印信息测试","type":"CP01","spnsrId":"00010000","offstAmt":"800"}]}
4.5 拓展参数说明（extendparams）
每个活动extendparams的字段均不相同，请按照 规范填写
1、支付宝点餐小程序活动填写规范
只对交易方式为支付宝JS支付(A02)有效Extendparams的字段如下:
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
food_order_type |
点餐场景类型 |
String(32) |
否 |
qr_order（店内扫码点餐），pre_order（预点到店自提），home_delivery （外送到家），direct_payment（直接付款），other（其他） |
填写样例
extendparams={"food_order_type":"qr_order"}
2 、微信设备信息(device_info)
透传ISV服务商或门店商户的设备号到微信系统
|
参数 |
参数名称 |
数据类型 |
可空 |
备注 |
|
device_info |
设备号 |
String(32) |
是 |
终端设备号(门店号或收银设备ID)，注意：PC网页或JSAPI支付请传"WEB" |
填写样例
extendparams={"device_info":" 013467007045764"}
3、支付宝外部指定买家
ext_user_info内容为支付宝OPENAPI接口文档中ExtUserInfo的json字符串(String类型)
|
参数 |
参数类型 |
可空 |
长度 |
说明 |
示例 |
|
ext_user_info |
ExtUserInfo |
否 |
- |
外部指定卖家 |
- |
|
name |
String |
否 |
16 |
姓名 |
黎明 |
|
mobile |
String |
否 |
20 |
手机号 |
16578789955 |
|
cert_type |
String |
否 |
32 |
身份证：IDENTIFY_CARD、护照：PASSPORT |
IDENTIFY_CARD |
|
cert_no |
String |
可选 |
64 |
证件号 |
362334768769238881 |
|
fix_buyer |
String |
可选 |
8 |
是否强制校验付款人身份信息 |
F |
|
min_age |
String |
可选 |
3 |
允许的最小买家年龄，买家年龄必须大于等于所传数值 |
18 |
|
need_check_info |
String |
可选 |
1 |
是否强制校验身份信息 |
F |
填写样例:
例如，如果要控制18岁的用户才能交易
extendparams={"ext_user_info":"{\"need_check_info\":\"T\",\"min_age\":\"18\"}"}
4、支付宝停车行业活动接入
具体行业活动介绍参考官方说明，链接如下：
https://alipay.open.taobao.com/doc2/detail?&docType=1&articleId=108053
停车场订单埋点参数：industry_reflux_info(此参数为各2.0支付产品接口中extend_params的下级参数，包含在biz_content中，且特别注意industry_reflux_info为json对象)
|
参数 |
参数名称 |
类型（字节长度） |
参数说明 |
是否可为空 |
样例 |
|
industry_reflux_info |
场景数据 |
String(100) |
场景的数据表示. json 数组格式，根据场景不同的模型，参见industry_reflux_info参数说明” |
不可空 |
|
industry_reflux_info参数填充内容
|
参数 |
参数名称 |
类型（字节长度） |
参数说明 |
是否可为空 |
样例 |
|
scene_code |
场景标识 |
String(100) |
用于标识数据模型，由isdsp配置提供，固定parking_fee_order |
不可空 |
parking_fee_order |
|
channel |
渠道 |
String(32) |
场景的来源渠道，固定common_park_provider |
不可空 |
common_park_provider |
|
scene_data |
场景数据 |
json |
场景的数据表示. json 数组格式，根据场景不同的模型，参见“1.1.2scene_data参数说明” |
不可空 |
|
scene_data参数说明
|
参数 |
参数名称 |
类型（字节长度） |
参数说明 |
是否可为空 |
样例 |
|
license_plate |
车牌号 |
String(32) |
用户车辆车牌号 |
不可空 |
浙A3DK19 |
|
start_time |
入场时间 |
String(32) |
停车场入场时间(YY-MM-DD HH:MM:SS)。若获取不到入场时间，可用支付时间替代。 |
不可空 |
2017-06-13 17:30:26 |
|
end_time |
支付时间 |
String(32) |
停车场出场支付时间(YY-MM-DD HH:MM:SS) |
可空 |
2017-06-13 17:30:26 |
|
parking_time |
停车时长 |
String |
停车时长，单位秒 |
可空 |
1200 |
|
parking_lot_id |
停车场ID |
String(32) |
停车场编号，即alipay.eco.mycar.parking.parkinglotinfo.create(录入停车场信息)返回的parking_id |
不可空 |
PI1504848980306666666 |
|
parkling_lot_name |
停车场名称 |
String |
停车场名称 |
可空 |
山下停车场 |
|
parking_lot_longitude |
停车场经度 |
String |
停车场位置经度 |
可空 |
232.2323 |
|
parking_lot_latitude |
停车场纬度 |
String |
停车场位置纬度 |
可空 |
2323.232 |
|
city_code |
城市编码 |
String |
当前停车场城市编码，填省市即可，无需精确到区的城市编码 |
可空 |
110100 |
填写样例:
extendparams={\"sys_service_provider_id\":\"2088711077456570\",\"industry_reflux_info\":{\"scene_data\":{\"start_time\":\"2020-08-31 09:30:26\",\"license_plate\":\"川A1ph13\",\"parkling_lot_name\":\"测试停车场\",\"city_code\":\"510100\",\"parking_lot_id\":\"PI1596794061186322467\"},\"channel\":\"common_park_provider\",\"scene_code\":\"parking_fee_order\"}}
JSON数据格式如下：
{
"sys_service_provider_id":"2088711077456570",
"industry_reflux_info":{
"scene_data":{
"start_time":"2020-08-31 09:30:26",
"license_plate":"川A1ph13",
"parkling_lot_name":"四川测试停车场",
"city_code":"510100",
"parking_lot_id":"PI1596794061186322467"},
"channel":"common_park_provider",
"scene_code":"parking_fee_order"
}
}
5、微信扫码点餐订单标识
商户创建订单的时候往attach字段传入订单标识信息，支付成功后，有优惠将根据扫码点餐商户白名单和attach里面的订单标识判定是否为扫码点餐订单。
|
参数 |
参数名称 |
类型（字节长度） |
参数说明 |
是否可为空 |
样例 |
|
attach |
场景数据 |
String(127) |
|
不可空 |
|
extendparams={"attach":"OrderSource=FoodOrder"}
6、云闪付主扫/被扫交易终端号透传
商户在执行paytype=U01及统一被扫云闪付交易时，可透传收银机终端编号到银联系统。
|
参数 |
参数名称 |
类型（字节长度） |
参数说明 |
是否可为空 |
样例 |
|
uptermno |
场景数据 |
String(8) |
数字及字母，限8位 |
可空 |
|
填写样例:
extendparams={"uptermno":"12345678"}
4.6 终端信息字段说明
terminfo字段
|
参数 |
参数名称 |
取值 |
可空 |
最大长度 |
备注 |
|
termno |
终端号 |
8位数字 |
否 |
8 |
商户下唯一 |
|
devicetype |
设备类型 |
01：自动柜员机（含 ATM 和 CDM）和多媒体自助终端 |
否 |
2 |
|
|
termsn |
终端序列号 |
|
是 |
50 |
终端类型（device_type）填写为 02、03、04、05、06、08、09 或 10时，必须填写终端序列号。 |
|
encryptrandnum |
加密随机因子 |
仅在被扫支付类交易报文中出现：若付款码为 19 位数字，则取后6 位；若付款码为 EMV 二维码，则取其tag 57 的卡号/token 号的后 6 位 |
是 |
10 |
|
|
secrettext |
密文数据 |
仅在被扫支付类交易报文中出现：64bit 的密文数据，对终端硬件序列号和加密随机因子加密后的结果。本子域取值为：64bit 密文数据进行base64 编码后的结果。 |
是 |
16 |
|
|
appversion |
终端程序版本号 |
|
是 |
8 |
终端应用程序的版本号。应用程序变更应保证版本号不重复。当长度不足时，右补空格。 |
|
longitude |
经度 |
经度信息格式：1位正负号+3位整数 +1位小数点 +5位小数， +表示东经， -表示西经，例如 +121.48352 |
是 |
16 |
银联扫码必送 |
|
latitude |
纬度 |
纬度信息格式：1位正负号+2位整数+1位小数点 +6 位小数，+表示北纬， -表示南纬，例如+31.221345或-03.561345 |
是 |
16 |
银联扫码必送 |
|
deviceip |
终端IP |
|
是 |
40 |
商户端终端设备 IP 地址。注：如经、维度信息未上送，该字段必送。 |
示例
terminfo={"termsn":"dfjskljioe13238023","longitude":"+121.48352","latitude":"-03.561345","termno":"00000001","devicetype":"11"}
4.7 asinfo字段说明
该字段提供对接方上送指定分账信息。如果上送此字段，必须开通数字营销资金管理功能。
- 最多支持3层分账。延时分账业务只支持一层。
- splitIdType为0-机构的主体类型时，不需要传splitCode和splitId，其他类型必须传splitCode或splitId，都传以splitId为准。
- splitIdType为0-机构或3-分佣方时，上送金额为最终分账金额，不再匹配系统配置的分账规则进行分账。
- 每层未全部分完时，剩余部分默认分账到对应的上层分账主体中，且不再匹配系统配置的分账规则进行分账。(建议：对未分完的部分，为了简化商户对接部分退款的处理，商户进行计算与管理，一并上送到分账信息中，splitIdType传3。否则商户在进行部分退款退分账未分完部分时，业务处理会比较复杂)。
- 延时分账splitIdType支持0、3。
- 退款
- 整单退时，不需要上送splitList字段，如果上送splitList字段，则按部分退款规则处理
- 部分退款，若需要各个分账完均摊退款金额，则不需要上送splitList，系统会自动计算各个分账主体退的金额;
- 部分退款，非均摊退款时，需要上送各分账方完整的退款分账规则。若上送的分账方对应的订单分账存在下级分账时，需要上送指定下级退款的分账规则，包含默认的分账。
- 部分退款，指定退分账未分完的部分时，splitIdType传3。
- 延时分账退款时，若已存在部分分账确认的子单号，则未分账确认部分不可退款，如果要对未分账确认部分进行退款，则需先调用分账确认接口分账到收款店铺后再进行退款。若整笔订单未进行分账确认，则可发起退款。
|
参数 |
参数名称 |
取值 |
|
splitIdType |
分账主体类型 |
0-机构、1-店铺，2-大类，3-分佣方，4-商品 |
|
splitCode |
分账主体CODE |
数字营销的店铺、大类、商品、分佣方等的code，分账主体类型为0时可不传 |
|
splitId |
分账主体ID |
数字营销的店铺、大类、商品、分佣方等的ID，分账主体类型为0时可不传 |
|
amount |
分账金额 |
金额，单位分 |
|
remark |
备注 |
|
|
subReqSn |
分账子订单号 |
延时分账业务，需要上送 |
|
splitList |
下层分账 |
asinfo |
示例：订单收款0.3元（30分）
[
{
"splitIdType": 1,
"splitCode": "10668",
"amount": 10,
"remark": "分给店铺10668"
},
{
"splitIdType": 3,
"splitId": "10666",
"amount": 10,
"remark": "分给分佣方10666"
},
{
"splitIdType": 0,
"amount": 10,
"remark": "分给平台机构"
}
]
说明：分给平台和10666的为最终分账结果，即到账金额；分给10668的0.1元，若系统配置有分账规则，则还要根据配置的分账规则继续进行分账处理。
4.8 交易方式
W01 微信扫码支付
W02 微信JS支付
W06 微信小程序支付
W11 微信订单支付
A01 支付宝扫码支付
A02 支付宝JS支付
U01 银联扫码支付(CSB)
U02 银联JS支付
S01 数币扫码支付
S03 数字货币H5
I01聚合支付（字母I）
IM01微信小程序聚合支付
4. 9 splitlist字段说明
该字段用于订单支付/退款/查询/通知接口返回分账结果信息。
|
参数 |
参数名称 |
取值 |
|
splitidtype |
分账主体类型 |
0-平台、1-店铺，3-分佣方 |
|
splitcode |
分账主体CODE |
splitIdType为0时，若为接口上送，则为空；若为系统分账规则分账，则为账户外部编号 |
|
splitid |
分账主体ID |
splitIdType为0时，若为接口上送，则为机构ID；若为系统分账规则分账，则为账户ID |
|
splitname |
分账主体名称 |
splitIdType为0时，若为接口上送，则为机构名称；若为系统分账规则分账，则为账户名称 |
|
amount |
分账金额 |
金额，单位分 |
|
remark |
备注 |
交易时上送的备注 |
|
subreqsn |
分账子订单号 |
延时分账的子订单号 |