API                Q&A

付付开放接口 V1.1.1


修订记录
日期 描述 版本号 修改人
2017-07-01 初始版本 V1.0.0
2017-08-16 格式化文档,添加异步通知接口,添加相关接口说明 V1.0.5
2017-08-28 1、主扫支付添加超时时间;
2、主扫支付subAppid更名为subAppId。
jcouyang
2017-10-19 异步通知添加busi_id和channel_trade_no返回 V1.0.6
2017-10-25 B扫C接口添加phone_code字段 V1.0.7 jcouyang
2017-10-31 查询和异步通知返回添加phone_code字段 V1.0.8 jcouyang
2017-12-12 1、查询,异步通知,刷卡支付返回借贷记标识字段;
2、添加关闭订单接口,修改撤销接口。
V1.0.9 jcouyang
2017-12-25 异步通知添加merchant_param字段
2017-12-30 添加退款查询接口 V1.1.0 jcouyang
2018-01-15 1、接口添加时区字段time_zone;
2、添加对海外的支持,涉及到资金的交易添加汇率和转换后的人民币金额等相关字段;
3、被扫支付和查询接口添加授权码的返回。
V1.1.1 jcouyang
2017-12-25 异步通知添加merchant_param字段
2017-12-25 异步通知添加merchant_param字段


一  概述


1.1  基本说明

该接口基于HTTP/HTTPS实现,请求方式为POST,字符集统一为UTF-8,请求与返回报文格式均为JSON。


1.2 签名计算

Sign的计算方法为:sign=MD5(timestamp+mchtKey+bodyContent):timestamp其中,timestamp为时间戳(Java开发者可以通过System.currentTimeMillis()进行获取)。mchtKey为付付分配到商户的密钥。签名计算时候要去掉bodyContent中所有空格和换行符,计算出的sign为32位的小写字母字符串。

假设timestamp=1502675456531,分配到商户的KEY为32个1,请求报文如下:

{
    "busi_id": "581010199011345",
    "operator_id": "test1",
    "terminal_id": "收银机1",
    "total_fee": "250",
    "channel_type": "1",
    "auth_code": "288886863488188613",
    "pay_subject": "測試商品1",
    "out_trade_no": "d2dbe5fb-fc71-4bfe-848f-a24875d9169c",
    "fee_type": "CNY"
}

按照签名计算方法,则有:sign=MD5(1502675456531111111111111111111111111111111111111111{"busi_id":"581010199011345","operator_id":"test1",
"terminal_id":"收银机1","total_fee":"250","channel_type":"1","auth_code":"288886863488188613","pay_subject":"测试商品1","out_trade_no":"d2dbe5fb-fc71-4bfe-848f-a24875d9169c","fee_type":"CNY"})
最后得到:sign=400073a70beecbab91780a9a4973c38f:1502675456531


1.3  请求地址

正式环境:BASE_URL=https://www.ffdzpay.com/gateway/pay
       测试环境:BASE_URL=



二  交易部分


2.1 被扫交易


请求地址:BASE_URL/order?sign={sign}
       其中,sign见【1.2签名算法】计算部分。 需要注意的是,sign不在请求列表参数中,而是放在URL当中(以下所有交易均如此)。被扫支付即B扫C,商户扫描顾客手机上的条码码然后发起支付。被扫接口超时时间80秒,如果80秒内没有完成支付,本次交易订单会自动撤销。该交易为同步交易。
        注意:请求地址中,{sign}中的{}无需上送,这里的{sign}是一个整体,意思是算出来的签名,以下与此类似。


2.1.1  请求参数列表

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String(32) 商户编号由平台统一分配 不可空 0010000001
operator_id 操作员编号 String(32) 操作员编号 可空 oper01
terminal_id 设备编号 String(32) 设备编号 可空 dev01
merchant_param 用户参数 String(127) 用户参数,采用base64编码,接口返回原样返回 可空 01000001
store_id 门店编号 String(32) 门店编号 可空 02016
total_fee 交易金额 Integer 以分为单位 不可空 158
discount_amount 可打折金额 Integer 以分为单位 目前两个字段暂时未用到
undiscount_amount 不可打折金额 Integer 以分为单位
channel_type 支付渠道 Integer 请参见 “附录2支付渠道字典”(传0自动判定渠道) 不可空 0
auth_code 支付用户动态码 String(100) 支付宝微信钱包用户动态码(通过扫描获得) 不可空 284214903060794755
out_trade_no 交易上行流水号 String(32) 商户交易上行流水号(需要唯一) 不可空 20150324001069125999
pay_subject 支付描述信息 String(100) 支付描述信息 不可空 二维码产品支付
fee_type 币种。默认CNY。 String(10) 货币类型 不可空 CNY,支持泰铢THB
time_zone 时区 String(64) 交易所在地的时区 可为空 默认:中国标准时间;Asia/Shanghai;+08:00

2.1.2  请求报文样例

{
    "busi_id": "581010199011345",
    "operator_id": "test1",
    "terminal_id": "收银机1",
    "total_fee": "250",
    "channel_type": "1",
    "auth_code": "288886863488188613",
    "pay_subject": "測試商品",
    "out_trade_no": "d2dbe5fb-fc71-4bfe-848f-a24875d9169c",
    "fee_type": "CNY"
}

2.1.3  返回参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.5返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String date对象return_code=FAIL的原因说明 SOUNDWAVE_PARSER_FAIL
channel_type 支付渠道 Integer 请参见 “附录2支付渠道字典” 1
out_trade_no 交易上行流水号 String 商户交易上行流水号 20150324001069125999
trade_no 交易下行流水号 String 平台交易流水号 1435736619488
channel_trade_no 渠道流水号 String 渠道流水号,支付宝、微信或其他交易渠道的流水号 2088110245121545154
phone_code 手机码 String 支付完成后,手机上显示的商户订单号,各个渠道有所区别 175580212567201710254130450135
auth_code 授权码 String 上送的授权码,原样返回
merchant_param 用户参数 String 用户参数,采用base64编码,接口返回原样返回 01000001
operator_id 操作员编号 String 操作员编号 oper01
terminal_id 设备编号 String 设备编号 dev01
begin_time 交易时间 String 交易时间yyyyMMddHHmmss 20170711145955
end_time 结束时间 String 结束时间yyyyMMddHHmmss 20170711150000
total_fee 交易金额 Integer 以分为单位 158
fee_type 货币类型 String
fee_type 货币类型 String
exchange_rate 汇率 String 如果fee_type不等于CNY,则该字段为fee_type对应的当日汇率,元为单位(一些汇率会精确到分的下一位甚至更多,不宜采用整型数据) 4.93
trans_amount_cny 人民币扣款金额 Integer 单位为分,fee_type不为CNY时,通过汇率转换后得到的人民币支付金额。
state 交易状态 Integer
credit 借贷记标识 String 借贷标识。可选值:
credit:信用卡
pcredit:花呗(仅支付宝)
debit:借记卡
balance:余额
unknown:未知
time_zone 时区 String(64) 交易所在地的时区

2.1.4  返回报文样例

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "SUCCESS",
    "channel_type": "1",
    "out_trade_no": "63c27efb-a133-4da0-91f3-6e7744b66825",
    "trade_no": "20170711100000236135",
    "channel_trade_no": "2017071121001004640200334121",
    "operator_id": "test1",
    "terminal_id": "收银机1",
    "begin_time": "20170711145955",
    "end_time": "20170711150000",
    "total_fee": 250,
    "fee_type": "HKD",
    "state": 1
     }
}


2.2  主扫交易

请求地址:BASE_URL/preOrder?sign={sign}
        该交易有两种模式,一种是二维码由我方生成,合作方获得二维码后,进行展示即可。另外一种是,商户按照支付宝微信的授权流程获取appid或者openid等相关参数发起预下单,然后按照支付宝微信的官网发起JSAPI支付。五分钟内,该笔交易未完成,后台会发起撤单交易。


2.2.1  请求参数列表

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String(32) 商户编号由平台统一分配 不可空 0010000001
operator_id 操作员编号 String(32) 操作员编号 可空 oper01
merchant_param 用户参数 String(127) 用户自定义参数,采用BASE64编码,接口返回原样返回 可空 01000001
store_id 门店编号 String(32) 门店编号 可空 02016
total_fee 交易金额 Integer 以分为单位 不可空 158
channel_type 支付渠道 Integer 请参见 “附录2支付渠道字典”(trade_type=QRCODE时传0自动判定渠道) 不可空 0
busi_id 商户编号 String(32) 商户编号由平台统一分配 不可空 0010000001
out_trade_no 交易上行流水号 String(50) 商户交易上行流水号(需要唯一) 不可空 20150324001069125999
pay_subject 支付描述信息 String(100) 支付描述信息 不可空 二维码产品支付
fee_type 交易币种 String(32) 货币类型 不可空 CNY
openId 用户标识,消费者用户标识。 String(10) 支付宝alipayid或者微信openId 可空 类型为JSAPI 必须填写
openId---用户标识,消费者用户标识。备注:
1.支付宝支付时,要求上送用户在支付宝唯一用户号user_id,获取流程请参考:https://doc.open.alipay.com/docs/doc.htm?treeId=220&articleId=105337&docType=1#s5
2.微信支付时,要求上送用户在合作方subAppid下唯一标识openid,获取流程请参考:http://mp.weixin.qq.com/wiki/17/c0f37d5704f0b64713d5d2c37b468d75.html
notifyUrl 交易通知地址。 String(10) 商户的交易通知地址 可空
subAppId 微信APPID String(10) 如为微信JSAPI支付,则必填 可空 类型为JSAPI 必须填写
trade_type 交易类型 String(10) QRCODE:一码付JSAPI:JSAPI支付 可空 默认JSAPI
time_expire 超时时间 Integer 订单有效期。指定订单的支付有效时间(以分钟计算),超过有效时间用户将无法支付。取值范围为:1-1440 可空 默认五分钟
time_zone 时区 String 交易所在地的时区-1440 可为空

2.2.2  请求报文样例

{
    "busi_id": "733010220151343",
    "operator_id": "测试操作员",
    "terminal_id": "05315830",
    "total_fee": "10",
    "channel_type": "1",
    "auth_code": "111",
    
    "pay_subject": "测试商户",
    "out_trade_no": "8ce68a7d-f422-4714-95ba-c3fcc737d86a",
    "fee_type": "CNY",
    "openId": "2088102172184723",
    "notifyUrl": "http://baidu.com"
     }

2.2.3  返回参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “3.5返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_msg 操作信息 String date对象return_code=FAIL的原因说明 SOUNDWAVE_PARSER_FAIL
trade_no 交易下行流水号 String 平台返回的交易流水号 1435736619488
out_trade_no 交易流水号 String 商户交易上行流水号(需要唯一) 20150324001069125999
prePayId 支付宝交易号 String 支付宝交易号 2015042321001004720200028594
payInfo 微信支付参数 String 微信公众号支付参数 见下一行
payInfo示例: {"appId":"wx17e91dae2802695e","timeStamp":"1502466163850", "status":"0","signType":"MD5",
"package":"prepay_id=wx20170811234243933827008d0347249 790","callback_url":null,"nonceStr":
"1502466163850","paySign":"A844D51548F5460847BBBCC1C864F317"}
qr_code 一码付地址 String 一码付地址,商户把改地址显示成二维码让用户用支付宝或者微信扫 http://www.ffdzpay.com/online/pay/?id=733010020151348&
tradeNo=20170811100000235332&price=0.01
time_zone 时区 String 交易所在地的时区

2.2.4  返回报文样例

第一种情况,一码付请求的支付返回:

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "SUCCESS",
    "out_trade_no": "deca1cd8-e4dc-42de-a4b6-9440d64af6ff",
    "trade_no": "20170724100000236187",
    "qr_code": "http://www.ffdzpay.com/online/pay/?id=733010020151348&tradeNo=20170811100000235332&price=0.01"
    }
}

第二种情况,支付宝JSAPI支付的返回:

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "SUCCESS",
    "out_trade_no": "deca1cd8-e4dc-42de-a4b6-9440d64af6ff",
    "trade_no": "20170724100000236187",
    "prePayId": "2017072421001004720201154848"
    }
}

第三种情况,微信JSAPI支付的返回:

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "SUCCESS",
    "out_trade_no": "deca1cd8-e4dc-42de-a4b6-9440d64af6ff",
    "trade_no": "20170724100000236187",
    "payInfo": "{"appId":"wx17e91dae2802695e","timeStamp":"1502466163850","status":"0","signType":"MD5","package":"prepay_id=wx20170811234243933827008d0347249790","callback_url":null,"nonceStr":"1502466163850","paySign":"A844D51548F5460847BBBCC1C864F317"}"
    }
}

2.2.5  H5调起支付API

创建订单+JSAPI唤起收银台支付在线文档:
       https://doc.open.alipay.com/docs/doc.htm?&docType=1&articleId=105591

微信H5 API接口地址如下:
       https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=7_7&index=6



2.3  异步通知

目前该交易仅发生在主扫支付模式下。当平台接收到后端支付渠道的通知后,会向合作方提供的notifyUrl发起支付通知,通知URL为【2.2主扫交易】中提供的notifyUrl字段。outNofityUrl=notifyUrl?sign={sign}

商户接收到通知后(返回字符串SUCCESS)停止通知,否则轮询通知5(返回字符串SUCCESS)中断,间隔5秒。如果用户已经支付但商户端没有收到通知的情况下,需要商户端主动调用查询接口获取订单状态。


2.3.1  通知参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “3.5返回样例”
return_msg 响应信息 String
data 响应数据 Object
busi_id 商户号 String 平台分配的商户号
channel_trade_no 渠道订单号 String 后端渠道的订单号
trade_no 交易下行流水号 String 平台返回的交易流水号 1435736619488
out_trade_no 交易流水号 String 商户交易上行流水号(需要唯一) 20150324001069125999
phone_code 手机码 String 支付完成后,手机上显示的商户订单号,各个渠道有所区别 175580212567201710254130450135
operator_id 操作员编号 String 操作员编号 oper01
terminal_id 设备编号 String 设备编号 dev01
merchant_param 商户自定义参数 String 商户在发起交易是上送的自定义参数
begin_time 交易时间 String 交易时间yyyyMMddHHmmss 20170711145955
end_time 结束时间 String 结束时间yyyyMMddHHmmss 20170711150000
total_fee 交易金额 Integer 以分为单位 158
fee_type 货币类型 String 默认 CNY
exchange_rate 汇率 String 如果fee_type不等于CNY,则该字段为fee_type对应的当日汇率,元为单位(一些汇率会精确到分的下一位甚至更多,不宜采用整型数据) 4.93
trans _amount_cny 人民币扣款金额 Integer 单位为分,fee_type不为CNY时,通过汇率转换后得到的人民币支付金额。
credit String 借贷记标识 String 借贷标识。可选值:
credit:信用卡
pcredit:花呗(仅支付宝)
debit:借记卡
balance:余额
unknown:未知
time_zone 时区 String 交易所在地的时区

2.3.2  通知报文样例

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "channel_type": "2",
    "out_trade_no": "8f02c2a5-1e8f-44ce-911f-8dae85e6c80d",
    "trade_no": "20170815100000235428",
    "operator_id": "test",
    "terminal_id": "05315830",
    "begin_time": "20170815232121",
    "end_time": "20170815232146",
    "total_fee": 1,
    "fee_type": "CNY",
    "state": 1
    }
}


2.4  退款接口

请求地址:BASE_URL/refund?sign={sign}


2.4.1  请求参数列表

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String 商户编号由平台分配 不可空 0010000001
operator_id 操作员编号 String 操作员编号 不可空 oper01
terminal_id 设备编号 String 设备编号 不可空 dev01
refund_fee 退款金额 Integer 以分为单位,退款金额不能大于本金 不可空 158
refund_subject 退款描述 String 退款描述 不可空 商户退款
out_trade_no 交易上行流水号 String 上行流水号(需要唯一) 可空(二选一) 20150324001069125999
trade_no 交易下行流水号 String 平台返回下行流水号(和上行流水号二选一,有下行流水号优先使用下行流水号退款) 可空(二选一) 1435736619488
out_refund_no 退款流水号 String 商户退款流水号(需要唯一) 不可空 20150324001069125999
fee_type 币种。默认CNY。 String(10) 货币类型 不可空 CNY
time_zone 时区 String 交易所在地的时区 可为空

2.4.2  请求报文样例

{
    "busi_id": "581010199011345",
    "operator_id": "devid1",
    "out_refund_no": "b12959ea-3678-4ccc-b3b8-8d8a0a9fee41",
    "refund_fee": "25000",
    "terminal_id": "terminal1",
    "out_trade_no": "63c27efb-a133-4da0-91f3-6e7744b66825",
    "refund_subject": "退款",
    "fee_type": "CHY"
}

2.4.3  返回参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.6返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String Return_code=FAIL的原因说明 SOUNDWAVE_PARSER_FAIL
out_trade_no 交易上行流水号 String 商户交易上行流水号 20150324001069125999
trade_no 交易下行流水号 String 平台交易流水号 1435736619488
out_refund_no 退款流水号 String 原样返回
operator_id 操作员编号 String 操作员编号 oper01
terminal_id 设备编号 String 设备编号 dev01
begin_time 交易时间 String 交易时间yyyyMMddHHmmss 20170711145955
end_time 结束时间 String 结束时间yyyyMMddHHmmss 20170711150000
refund_fee 交易金额 Integer 以分为单位 158
fee_type 货币类型 String
exchange_rate 汇率 String 如果fee_type不等于CNY,则该字段为fee_type对应的当日汇率,元为单位(一些汇率会精确到分的下一位甚至更多,不宜采用整型数据) 4.93
refund_amount_cny 人民币扣款金额 Integer 单位为分,fee_type不为CNY时,通过汇率转换后得到的人民币支付金额。
channel_type 支付渠道 Integer 请参见 “附录2支付渠道字典”(传0自动判定渠道) 不可空
time_zone 时区 String 交易所在地的时区

2.4.4  返回报文样例

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
     },
    "data": {
    "return_code": "SUCCESS",
    "out_trade_no": "63c27efb-a133-4da0-91f3-6e7744b66825",
    "trade_no": "20170711100000236135",
     "operator_id": "devid1",
    "terminal_id": "terminal1",
    "begin_time": "20170711151343",
    "end_time": "20170711151348",
    "refund_fee": 250,
    "fee_type": "HKD",
    "out_refund_no": "c934b562-ffd7-4971-a877-c538db0b5409",
    "refund_no": "20170711100000236136"
    }
}


2.5  查询接口

请求地址:BASE_URL/query?sign={sign}


2.5.1  请求参数列表

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String 商户编号由平台分配 不可空 0010000001
out_trade_no 交易上行流水号 String 上行流水号(需要唯一) 不可空 20150324001069125999
trade_no 交易下行流水号 String 平台返回下行流水号(和上行流水号二选一,有下行流水号优先使用下行流水号退款) 可空 1435736619488
time_zone 时区 String 交易所在地的时区 可空

2.5.2  请求报文样例

{
    "trade_no": "20170706100000236103",
    "out_trade_no": "8aa699fb-74f2-4bb6-8cf6-14e61d2e6740",
    "busi_id": "581010199011345"
}

2.5.3  返回参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.6返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String Return_code=FAIL的原因说明 SOUNDWAVE_PARSER_FAIL
channel_type 支付渠道 Integer 请参见 “附录2支付渠道字典” 1
out_trade_no 交易上行流水号 String 商户交易上行流水号 20150324001069125999
trade_no 交易下行流水号 String 平台交易流水号 1435736619488
phone_code 手机码 String 支付完成后,手机上显示的商户订单号,各个渠道有所区别 175580212567201710254130450135
auth_code 授权码 String 上送的授权码,原样返回
channel_trade_no 渠道流水号 String 渠道流水号,支付宝、微信或其他交易渠道的流水号 2088110245121545154
merchant_param 用户参数 String 用户参数,采用base64编码,接口返回原样返回 01000001
operator_id 操作员编号 String 操作员编号 oper01
terminal_id 设备编号 String 设备编号 dev01
begin_time 交易时间 String 交易时间yyyyMMddHHmmss 20170711145955
end_time 结束时间 String 结束时间yyyyMMddHHmmss 20170711150000
refund_fee 交易金额 Integer 以分为单位 158
fee_type 货币类型 String
exchange_rate 汇率 String 如果fee_type不等于CNY,则该字段为fee_type对应的当日汇率,元为单位 4.93
refund_amount_cny 人民币扣款金额 Integer 单位为分,fee_type不为CNY时,通过汇率转换后得到的人民币支付金额。
credit 借贷记标识 String 借贷标识。可选值:
credit:信用卡
pcredit:花呗(仅支付宝)
debit:借记卡
balance:余额
unknown:未知
time_zone 时区 String 交易所在地的时区

2.5.4  返回报文样例

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "SUCCESS",
    "channel_type": "1",
    "out_trade_no": "b2d67d35-9dc1-458f-a982-4db358192a9b",
    "trade_no": "20170706100000236103",
    "channel_trade_no": "2017070621001004550200361946",
    "operator_id": "test1",
    "terminal_id": "收银机1",
    "begin_time": "20170706112203",
    "end_time": "20170706112208",
    "fee_type": "HKD",
    "state": 1
    }
}


2.6  撤单接口

请求地址:BASE_URL/cancel?sign={sign}
       本接口针对刷卡支付(被扫)模式,用户长时间未等到订单终态或者一直超时,调用本接口撤销订单。当认定该订单已支付成功或支付失败,则撤销失败。调用订单撤销前请先进行订单查询。

最早可撤销时间在订单创建之后15秒后
       撤销交易需要控制在1:00—23:00,其余时间不允许进行撤销交易。
        一般而言,没有特殊需求,不建议发起该交易。如确实有该需求,请与我方开发人员进行沟通。


2.6.1  请求参数列表

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String 商户编号由平台分配 不可空 0010000001
operator_id 操作员编号 String 操作员编号 不可空 oper01
terminal_id 设备编号 String 设备编号 不可空 dev01
out_trade_no 交易上行流水号 String 上行流水号(需要唯一) 不可空 20150324001069125999
trade_no 交易下行流水号 String 平台返回下行流水号(和上行流水号二选一,有下行流水号优先使用下行流水号退款) 可空 1435736619488
time_zone 时区 String 交易所在地的时区 可空

2.6.2  请求报文样例

{
    "busi_id": "733010120151359",
    "operator_id": "devid1",
    "terminal_id": "test1",
    "out_trade_no": "b2d67d35-9dc1-458f-a982-4db358192a9b",
    "trade_no": "20170706100000236126"
}

2.6.3  返回参数列表

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.6返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String Return_code=FAIL的原因说明 SOUNDWAVE_PARSER_FAIL
time_zone 时区 String 交易所在地的时区

2.6.4  返回报文样例

{
    "result": {
    "return_msg": "OK",
    "return_code": "SUCCESS"
    },
    "data": {
    "return_code": "FAIL",
    "return_msg": "CHARGE_NONEXISTENT"
    }
}


2.7  关闭订单

请求地址:BASE_URL/close?sign={sign}
       该接口针对主扫模式,当订单创建后,消费者长时间未付款,合作方可通过本接口关闭订单。

如果订单未支付,关闭订单;
       如果订单已经成功或支付失败,无法关闭,返回订单已成功或已失败。
        一般而言,没有特殊需求,不建议发起该交易。如确实有该需求,请与我方开发人员进行沟通。


2.7.1  请求报文

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String 商户编号由平台分配 不可空 0010000001
operator_id 操作员编号 String 操作员编号 不可空 oper01
terminal_id 设备编号 String 设备编号 不可空 dev01
out_trade_no 交易上行流水号 String 上行流水号,原订单的外部订单号 不可空 20150324001069125999
time_zone 时区 String 交易所在地的时区 可空

2.7.2  返回报文

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.6返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String Return_code=FAIL的原因说明
out_trade_no 外部订单号 String 原样返回
trade_no 平台订单号 String
time_zone 时区 String 交易所在地的时区


2.8  退款查询

请求地址:BASE_URL/refundQuery?sign={sign}
       该接口提供退款交易的结果回查功能。


2.8.1  请求报文

参数 参数名称 类型 参数说明 是否可为空 样例
busi_id 商户编号 String 商户编号由平台分配 不可空 0010000001
operator_id 操作员编号 String 操作员编号 不可空 oper01
terminal_id 设备编号 String 设备编号 不可空 dev01
out_trade_no 原商户退款流水号 String 原来商户发起退款交易上送的退款的流水号 不可空 20150324001069125999
time_zone 时区 String 交易所在地的时区 可空

2.8.2  返回报文

参数 参数名称 类型 参数说明 样例
result 请求结果 Object 请求接口响应码。节点子节点包括: return_code:返回代码。详情参见 “附录5返回代码数据字典” return_msg:返回消息 请参见 “2.6返回样例”
return_code 响应代码 String SUCCESS/FAIL
return_msg 响应信息 String
data部分,当result.return_code=SUCCESS是data部分才有内容
return_code 操作代码 String SUCCESS/FAIL
return_msg 操作信息 String Return_code=FAIL的原因说明
out_trade_no 商户退款单号 String 原样返回
trade_no 平台订单号 String
trade_status 退款状态 String 1、 成功:succ
2、 失败:fail
3、 退款中:refunding
以下字段仅当trade_status=succ时有返回
refund_fee 退款金额 Integer 退款金额,单位为分
refund_subject 退款原因 String 原退款交易上送的退款原因
gmt_refund_time 退款完成时间 String 退款完成时间,时间格式yyyyMMddHHmmss
operator_id 操作员编号 String 操作员编号
terminal_id 设备编号 String 设备编号
time_zone 时区 String 交易所在地的时区


三  附录


3.1  商品信息定义

参数 参数名称 类型 参数说明 是否可为空 样例
good_id 商品ID String 商品ID 不可空 2010
good_name 商品名称 String 商品名称 不可空 Iphone
good_class 商品分类 String 设备编码 不可空 手机
good_price 商品金额 String 以元为单位 不可空 4999.00
good_subject 商品简介 String 请参见“支付渠道附录” 不可空 数码产品
good_quantity 商品数量 String 需要唯一 不可空 1
good_showurl 商品展示网址 String 商品展示地址 可空 www.ffdzpay.com

3.2  支付渠道数据字典

支付渠道代码 支付渠道
0 被扫接口传0自动判定渠道
1 支付宝
2 微信

3.3  付款渠道数据字典

付款渠道代码 付款渠道
00 支付宝红包
10 支付宝余额
60 支付宝预存卡
30 支付宝集分宝
70 支付宝信用支付
40 折扣券
80 预付卡
90 信用支付(消费信贷)
11 微信支付
41 微信现金券支付

3.4  订单状态字典( 红色为退款订单状态

订单状态 含义
0 待付款
1 已付款
2 已撤单
3 申请撤单
4 部分退款
5 已退款
6 交易关闭
7 系统保留状态(查询时使用,同时查询退款和撤单记录)
8 退款中(平台未返回退款结果)
9 退款失败
10 待退款
11 退款成功
12 退款失败
13 退款取消
14 撤单成功

3.5  返回代码数据字典

订单状态 含义
SUCESS 成功
FAIL 失败
ILLEGAL_PARAMETER 参数错误
INVALID_SIGN 签名错误
AMT_ERROR 金额错误
DATABASE_ERROR 数据库连接异常
INVALID_CONTRACT 无效的签约状态
UNREGISTERED_BUSI 未注册的商户
EXCEPTION 未知异常
CHARGE_NONEXISTENT 交易记录不存在
SERVICE_UNAVAILABLE 服务不可用
HTTP_EXCEPTION HTTP请求异常
IO_EXCEPTION IO异常
CREATE_SECURITY_CONNECTION_ERROR 创建安全链接失败
AREADY_REVOKED 该订单已经撤销
SERIAL_REPEAT 上行流水号与系统中重复




更多疑问 全面解答

付付得正在线为您解答所有疑惑

免费咨询