API Q&A
付付開放接口 V1.1.1
| 修訂記錄 | |||
| 日期 | 描述 | 版本號 | 修改人 |
| 2017-07-01 | 初始版本 | V1.0.0 | |
| 2017-08-16 | 格式化文檔，添加異步通知接口，添加相關(guān)接口說明 | 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、添加關(guān)閉訂單接口，修改撤銷接口。 |
V1.0.9 | jcouyang |
| 2017-12-25 | 異步通知添加merchant_param字段 | ||
| 2017-12-30 | 添加退款查詢接口 | V1.1.0 | jcouyang |
| 2018-01-15 | 1、接口添加時區(qū)字段time_zone； 2、添加對海外的支持，涉及到資金的交易添加匯率和轉(zhuǎn)換后的人民幣金額等相關(guān)字段； 3、被掃支付和查詢接口添加授權(quán)碼的返回。 |
V1.1.1 | jcouyang |
| 2017-12-25 | 異步通知添加merchant_param字段 | ||
| 2017-12-25 | 異步通知添加merchant_param字段 | ||
一 概述
1.1 基本說明
該接口基于HTTP/HTTPS實現(xiàn)，請求方式為POST，字符集統(tǒng)一為UTF-8，請求與返回報文格式均為JSON。
1.2 簽名計算
Sign的計算方法為：sign=MD5(timestamp+mchtKey+bodyContent):timestamp其中，timestamp為時間戳（Java開發(fā)者可以通過System.currentTimeMillis()進行獲取）。mchtKey為付付分配到商戶的密鑰。簽名計算時候要去掉bodyContent中所有空格和換行符，計算出的sign為32位的小寫字母字符串。
假設(shè)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"
}
"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 請求地址
正式環(huán)境：BASE_URL=http://www.xnue.com.cn/gateway/pay
測試環(huán)境：BASE_URL=
二 交易部分
2.1 被掃交易
請求地址：BASE_URL/order?sign={sign}
其中，sign見【1.2簽名算法】計算部分。
需要注意的是，sign不在請求列表參數(shù)中，而是放在URL當中（以下所有交易均如此）。被掃支付即B掃C，商戶掃描顧客手機上的條碼碼然后發(fā)起支付。被掃接口超時時間80秒，如果80秒內(nèi)沒有完成支付，本次交易訂單會自動撤銷。該交易為同步交易。
注意：請求地址中，{sign}中的{}無需上送，這里的{sign}是一個整體，意思是算出來的簽名，以下與此類似。
2.1.1 請求參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 是否可為空 | 樣例 |
| busi_id | 商戶編號 | String(32) | 商戶編號由平臺統(tǒng)一分配 | 不可空 | 0010000001 |
| operator_id | 操作員編號 | String(32) | 操作員編號 | 可空 | oper01 |
| terminal_id | 設(shè)備編號 | String(32) | 設(shè)備編號 | 可空 | dev01 |
| merchant_param | 用戶參數(shù) | String(127) | 用戶參數(shù)，采用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 | 支付用戶動態(tài)碼 | String(100) | 支付寶微信錢包用戶動態(tài)碼(通過掃描獲得) | 不可空 | 284214903060794755 |
| out_trade_no | 交易上行流水號 | String(32) | 商戶交易上行流水號(需要唯一) | 不可空 | 20150324001069125999 |
| pay_subject | 支付描述信息 | String(100) | 支付描述信息 | 不可空 | 二維碼產(chǎn)品支付 |
| fee_type | 幣種。默認CNY。 | String(10) | 貨幣類型 | 不可空 | CNY，支持泰銖THB |
| time_zone | 時區(qū) | String(64) | 交易所在地的時區(qū) | 可為空 | 默認：中國標準時間;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"
}
"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 返回參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 樣例 |
| result | 請求結(jié)果 | Object | 請求接口響應碼。節(jié)點子節(jié)點包括： return_code：返回代碼。詳情參見 “附錄5返回代碼數(shù)據(jù)字典” return_msg：返回消息 | 請參見 “2.5返回樣例” |
| return_code | 響應代碼 | String | SUCCESS/FAIL | |
| return_msg | 響應信息 | String | ||
| data部分，當result.return_code=SUCCESS是data部分才有內(nèi)容 | ||||
| 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 | 支付完成后，手機上顯示的商戶訂單號，各個渠道有所區(qū)別 | 175580212567201710254130450135 |
| auth_code | 授權(quán)碼 | String | 上送的授權(quán)碼，原樣返回 | |
| merchant_param | 用戶參數(shù) | String | 用戶參數(shù)，采用base64編碼，接口返回原樣返回 | 01000001 |
| operator_id | 操作員編號 | String | 操作員編號 | oper01 |
| terminal_id | 設(shè)備編號 | String | 設(shè)備編號 | dev01 |
| begin_time | 交易時間 | String | 交易時間yyyyMMddHHmmss | 20170711145955 |
| end_time | 結(jié)束時間 | String | 結(jié)束時間yyyyMMddHHmmss | 20170711150000 |
| total_fee | 交易金額 | Integer | 以分為單位 | 158 |
| fee_type | 貨幣類型 | String | ||
| fee_type | 貨幣類型 | String | ||
| exchange_rate | 匯率 | String | 如果fee_type不等于CNY，則該字段為fee_type對應的當日匯率，元為單位（一些匯率會精確到分的下一位甚至更多，不宜采用整型數(shù)據(jù)） | 4.93 |
| trans_amount_cny | 人民幣扣款金額 | Integer | 單位為分，fee_type不為CNY時，通過匯率轉(zhuǎn)換后得到的人民幣支付金額。 | |
| state | 交易狀態(tài) | Integer | ||
| credit | 借貸記標識 | String | 借貸標識。可選值： credit：信用卡 pcredit：花唄（僅支付寶） debit：借記卡 balance：余額 unknown：未知 |
|
| time_zone | 時區(qū) | String(64) | 交易所在地的時區(qū) | |
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
}
}
"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}
該交易有兩種模式，一種是二維碼由我方生成，合作方獲得二維碼后，進行展示即可。另外一種是，商戶按照支付寶微信的授權(quán)流程獲取appid或者openid等相關(guān)參數(shù)發(fā)起預下單，然后按照支付寶微信的官網(wǎng)發(fā)起JSAPI支付。五分鐘內(nèi)，該筆交易未完成，后臺會發(fā)起撤單交易。
2.2.1 請求參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 是否可為空 | 樣例 |
| busi_id | 商戶編號 | String(32) | 商戶編號由平臺統(tǒng)一分配 | 不可空 | 0010000001 |
| operator_id | 操作員編號 | String(32) | 操作員編號 | 可空 | oper01 |
| merchant_param | 用戶參數(shù) | String(127) | 用戶自定義參數(shù)，采用BASE64編碼，接口返回原樣返回 | 可空 | 01000001 |
| store_id | 門店編號 | String(32) | 門店編號 | 可空 | 02016 |
| total_fee | 交易金額 | Integer | 以分為單位 | 不可空 | 158 |
| channel_type | 支付渠道 | Integer | 請參見 “附錄2支付渠道字典”（trade_type=QRCODE時傳0自動判定渠道） | 不可空 | 0 |
| busi_id | 商戶編號 | String(32) | 商戶編號由平臺統(tǒng)一分配 | 不可空 | 0010000001 |
| out_trade_no | 交易上行流水號 | String(50) | 商戶交易上行流水號(需要唯一) | 不可空 | 20150324001069125999 |
| pay_subject | 支付描述信息 | String(100) | 支付描述信息 | 不可空 | 二維碼產(chǎn)品支付 |
| 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 | 時區(qū) | String | 交易所在地的時區(qū)-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"
}
"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 返回參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 樣例 |
| result | 請求結(jié)果 | Object | 請求接口響應碼。節(jié)點子節(jié)點包括： return_code：返回代碼。詳情參見 “附錄5返回代碼數(shù)據(jù)字典” return_msg：返回消息 | 請參見 “3.5返回樣例” |
| return_code | 響應代碼 | String | SUCCESS/FAIL | |
| return_msg | 響應信息 | String | ||
| data部分，當result.return_code=SUCCESS是data部分才有內(nèi)容 | ||||
| return_msg | 操作信息 | String | date對象return_code=FAIL的原因說明 | SOUNDWAVE_PARSER_FAIL |
| trade_no | 交易下行流水號 | String | 平臺返回的交易流水號 | 1435736619488 |
| out_trade_no | 交易流水號 | String | 商戶交易上行流水號(需要唯一) | 20150324001069125999 |
| prePayId | 支付寶交易號 | String | 支付寶交易號 | 2015042321001004720200028594 |
| payInfo | 微信支付參數(shù) | String | 微信公眾號支付參數(shù) | 見下一行 |
| 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.xnue.com.cn/online/pay/?id=733010020151348& tradeNo=20170811100000235332&price=0.01 |
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | |
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.xnue.com.cn/online/pay/?id=733010020151348&tradeNo=20170811100000235332&price=0.01"
}
}
"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.xnue.com.cn/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"
}
}
"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"}"
}
}
"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調(diào)起支付API
創(chuàng)建訂單+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 異步通知
目前該交易僅發(fā)生在主掃支付模式下。當平臺接收到后端支付渠道的通知后，會向合作方提供的notifyUrl發(fā)起支付通知，通知URL為【2.2主掃交易】中提供的notifyUrl字段。outNofityUrl=notifyUrl?sign={sign}
商戶接收到通知后(返回字符串SUCCESS)停止通知，否則輪詢通知5（返回字符串SUCCESS)中斷，間隔5秒。如果用戶已經(jīng)支付但商戶端沒有收到通知的情況下，需要商戶端主動調(diào)用查詢接口獲取訂單狀態(tài)。
2.3.1 通知參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 樣例 |
| result | 請求結(jié)果 | Object | 請求接口響應碼。節(jié)點子節(jié)點包括： return_code：返回代碼。詳情參見 “附錄5返回代碼數(shù)據(jù)字典” return_msg：返回消息 | 請參見 “3.5返回樣例” |
| return_msg | 響應信息 | String | ||
| data | 響應數(shù)據(jù) | Object | ||
| busi_id | 商戶號 | String | 平臺分配的商戶號 | |
| channel_trade_no | 渠道訂單號 | String | 后端渠道的訂單號 | |
| trade_no | 交易下行流水號 | String | 平臺返回的交易流水號 | 1435736619488 |
| out_trade_no | 交易流水號 | String | 商戶交易上行流水號(需要唯一) | 20150324001069125999 |
| phone_code | 手機碼 | String | 支付完成后，手機上顯示的商戶訂單號，各個渠道有所區(qū)別 | 175580212567201710254130450135 |
| operator_id | 操作員編號 | String | 操作員編號 | oper01 |
| terminal_id | 設(shè)備編號 | String | 設(shè)備編號 | dev01 |
| merchant_param | 商戶自定義參數(shù) | String | 商戶在發(fā)起交易是上送的自定義參數(shù) | |
| begin_time | 交易時間 | String | 交易時間yyyyMMddHHmmss | 20170711145955 |
| end_time | 結(jié)束時間 | String | 結(jié)束時間yyyyMMddHHmmss | 20170711150000 |
| total_fee | 交易金額 | Integer | 以分為單位 | 158 |
| fee_type | 貨幣類型 | String | 默認 | CNY |
| exchange_rate | 匯率 | String | 如果fee_type不等于CNY，則該字段為fee_type對應的當日匯率，元為單位（一些匯率會精確到分的下一位甚至更多，不宜采用整型數(shù)據(jù)） | 4.93 |
| trans _amount_cny | 人民幣扣款金額 | Integer | 單位為分，fee_type不為CNY時，通過匯率轉(zhuǎn)換后得到的人民幣支付金額。 | |
| credit String | 借貸記標識 | String | 借貸標識。可選值： credit：信用卡 pcredit：花唄（僅支付寶） debit：借記卡 balance：余額 unknown：未知 |
|
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) |
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
}
}
"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 請求參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 是否可為空 | 樣例 |
| busi_id | 商戶編號 | String | 商戶編號由平臺分配 | 不可空 | 0010000001 |
| operator_id | 操作員編號 | String | 操作員編號 | 不可空 | oper01 |
| terminal_id | 設(shè)備編號 | String | 設(shè)備編號 | 不可空 | dev01 |
| refund_fee | 退款金額 | Integer | 以分為單位，退款金額不能大于本金 | 不可空 | 158 |
| refund_subject | 退款描述 | String | 退款描述 | 不可空 | 商戶退款 |
| out_trade_no | 交易上行流水號 | String | 上行流水號（需要唯一） | 可空(二選一) | 20150324001069125999 |
| trade_no | 交易下行流水號 | String | 平臺返回下行流水號(和上行流水號二選一，有下行流水號優(yōu)先使用下行流水號退款) | 可空(二選一) | 1435736619488 |
| out_refund_no | 退款流水號 | String | 商戶退款流水號（需要唯一） | 不可空 | 20150324001069125999 |
| fee_type | 幣種。默認CNY。 | String(10) | 貨幣類型 | 不可空 | CNY |
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | 可為空 |
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"
}
"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 返回參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 樣例 |
| result | 請求結(jié)果 | Object | 請求接口響應碼。節(jié)點子節(jié)點包括： return_code：返回代碼。詳情參見 “附錄5返回代碼數(shù)據(jù)字典” return_msg：返回消息 | 請參見 “2.6返回樣例” |
| return_code | 響應代碼 | String | SUCCESS/FAIL | |
| return_msg | 響應信息 | String | ||
| data部分，當result.return_code=SUCCESS是data部分才有內(nèi)容 | ||||
| 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 | 設(shè)備編號 | String | 設(shè)備編號 | dev01 |
| begin_time | 交易時間 | String | 交易時間yyyyMMddHHmmss | 20170711145955 |
| end_time | 結(jié)束時間 | String | 結(jié)束時間yyyyMMddHHmmss | 20170711150000 |
| refund_fee | 交易金額 | Integer | 以分為單位 | 158 |
| fee_type | 貨幣類型 | String | ||
| exchange_rate | 匯率 | String | 如果fee_type不等于CNY，則該字段為fee_type對應的當日匯率，元為單位（一些匯率會精確到分的下一位甚至更多，不宜采用整型數(shù)據(jù)） | 4.93 |
| refund_amount_cny | 人民幣扣款金額 | Integer | 單位為分，fee_type不為CNY時，通過匯率轉(zhuǎn)換后得到的人民幣支付金額。 | |
| channel_type | 支付渠道 | Integer | 請參見 “附錄2支付渠道字典”（傳0自動判定渠道） | 不可空 |
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | |
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"
}
}
"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 請求參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 是否可為空 | 樣例 |
| busi_id | 商戶編號 | String | 商戶編號由平臺分配 | 不可空 | 0010000001 |
| out_trade_no | 交易上行流水號 | String | 上行流水號（需要唯一） | 不可空 | 20150324001069125999 |
| trade_no | 交易下行流水號 | String | 平臺返回下行流水號(和上行流水號二選一，有下行流水號優(yōu)先使用下行流水號退款) | 可空 | 1435736619488 |
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | 可空 |
2.5.2 請求報文樣例
{
"trade_no": "20170706100000236103",
"out_trade_no": "8aa699fb-74f2-4bb6-8cf6-14e61d2e6740",
"busi_id": "581010199011345"
}
"trade_no": "20170706100000236103",
"out_trade_no": "8aa699fb-74f2-4bb6-8cf6-14e61d2e6740",
"busi_id": "581010199011345"
}
2.5.3 返回參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 樣例 |
| result | 請求結(jié)果 | Object | 請求接口響應碼。節(jié)點子節(jié)點包括： return_code：返回代碼。詳情參見 “附錄5返回代碼數(shù)據(jù)字典” return_msg：返回消息 | 請參見 “2.6返回樣例” |
| return_code | 響應代碼 | String | SUCCESS/FAIL | |
| return_msg | 響應信息 | String | ||
| data部分，當result.return_code=SUCCESS是data部分才有內(nèi)容 | ||||
| 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 | 支付完成后，手機上顯示的商戶訂單號，各個渠道有所區(qū)別 | 175580212567201710254130450135 |
| auth_code | 授權(quán)碼 | String | 上送的授權(quán)碼，原樣返回 | |
| channel_trade_no | 渠道流水號 | String | 渠道流水號，支付寶、微信或其他交易渠道的流水號 | 2088110245121545154 |
| merchant_param | 用戶參數(shù) | String | 用戶參數(shù)，采用base64編碼，接口返回原樣返回 | 01000001 |
| operator_id | 操作員編號 | String | 操作員編號 | oper01 |
| terminal_id | 設(shè)備編號 | String | 設(shè)備編號 | dev01 |
| begin_time | 交易時間 | String | 交易時間yyyyMMddHHmmss | 20170711145955 |
| end_time | 結(jié)束時間 | String | 結(jié)束時間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時，通過匯率轉(zhuǎn)換后得到的人民幣支付金額。 | |
| credit | 借貸記標識 | String | 借貸標識。可選值： credit：信用卡 pcredit：花唄（僅支付寶） debit：借記卡 balance：余額 unknown：未知 |
|
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | |
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
}
}
"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}
本接口針對刷卡支付（被掃）模式，用戶長時間未等到訂單終態(tài)或者一直超時，調(diào)用本接口撤銷訂單。當認定該訂單已支付成功或支付失敗，則撤銷失敗。調(diào)用訂單撤銷前請先進行訂單查詢。
最早可撤銷時間在訂單創(chuàng)建之后15秒后
撤銷交易需要控制在1:00—23:00，其余時間不允許進行撤銷交易。
一般而言，沒有特殊需求，不建議發(fā)起該交易。如確實有該需求，請與我方開發(fā)人員進行溝通。
2.6.1 請求參數(shù)列表
| 參數(shù) | 參數(shù)名稱 | 類型 | 參數(shù)說明 | 是否可為空 | 樣例 |
| busi_id | 商戶編號 | String | 商戶編號由平臺分配 | 不可空 | 0010000001 |
| operator_id | 操作員編號 | String | 操作員編號 | 不可空 | oper01 |
| terminal_id | 設(shè)備編號 | String | 設(shè)備編號 | 不可空 | dev01 |
| out_trade_no | 交易上行流水號 | String | 上行流水號（需要唯一） | 不可空 | 20150324001069125999 |
| trade_no | 交易下行流水號 | String | 平臺返回下行流水號(和上行流水號二選一，有下行流水號優(yōu)先使用下行流水號退款) | 可空 | 1435736619488 |
| time_zone | 時區(qū) | String | 交易所在地的時區(qū) | 可空 |
2.6.2 請求報文樣例
{
"busi_id": "733010120151359",
"operator_id": "devid1",
"terminal_id": "test1",
"out_trade_no": "b2d67d35-9dc1-458f-a982-4db358192a9b",
"trade_no": "20170706100000236126"
}
"busi_id": "733010120151359",
"operator_id": "devid1",
"terminal_id": "test1",
"out_trade_no": "b2d67d35-9dc1-458f-a982-4db358192a9b",
"trade_no": "20170706100000236126"
}
