話費充值接口文檔
接口版本：1.0
―、引言
1.1 文檔概述
本文檔提供話費充值接口規范說明，提供一整套的完整的接入示例(http 接口)供商戶參 考，可以幫助商戶開發人員快速完成接口開發與聯調，實現與話費充值系統的交易互聯。
公司官網：http://www.wikeyun.cn/
1.2 閱讀對象
本文閱讀對象：開發人員與微客雲系統對接支付相關的技術人員。
1.3 業務流程
1、打開控制台 https://control.wikeyun.cn/ 進行注冊賬號
2、點擊添加店鋪，只勾選CMS即可，或者店鋪ID保存。
3、聯系客服申請 app_key與app_secret 。
4、開發對接，需求在控制台進行預存。
二、話費充值接口
1、充值請求下單（post 表單提交）
網關URL：https://router.wikeyun.cn/rest/Recharge/pushOrder
| 參數名 |
類型 |
必填 |
參數說明 |
| store_id |
字符串 |
是 |
店鋪ID |
| mobile |
字符串 |
是 |
充值號碼 |
| order_no |
字符串 |
是 |
充值訂單號 |
| money |
整數 |
是 |
充值金額（100，200） |
| recharge_type |
整型 |
是 |
1快充 0慢充 |
| notify_url |
字符串 |
是 |
異步回調地址（POST） |
| change |
整數 |
否 |
失敗更換渠道充值 0 否 1是 不傳系統根據設置判斷 |
| source |
整形 |
否 |
是否強制渠道 |
注意：因為每個渠道價格不同，不同用戶提交的業務不同，默認不強制；
傳source字段則可以強制某渠道，強制快充走94折則，source傳6
失敗返回數據格式：
{"code":"1003","msg":"app_key不能為空","time":"1624868000","data":null}
成功返回數據格式：
{"code":"0000","msg":"推送成功","data":{"order_number":"xxxx"}}
2、回調通知
| 參數名 |
類型 |
參數說明 |
| order_no |
字符串 |
充值訂單號 |
| order_number |
字符串 |
官方訂單號 |
| status |
字符串 |
交易結果（0 待支付 1 已付 充值中 2充值成功 3充值失敗 需要退款 4退款成功 6待充值 7 已匹配） |
收到回調后，商戶必須同步返回字符串 success，否則平台認為商戶沒有收到回調，會重復發送5
次回調。
3、查詢接口（post 表單提交）
網關URL：https://router.wikeyun.cn/rest/Recharge/query
| 參數名 |
類型 |
必填 |
參數說明 |
| order_number |
字符串 |
是 |
官方訂單號 |
失敗返回數據格式：
{"code":"1003","msg":"app_key不能為空","time":"1624868000","data":null}
成功返回數據格式：
{"code":"0000","msg":"獲取成功","data":{"order_number":"xxxx","status":"1","mobile":"13786517891","amount":"100","order_no":"xxxx"}}
4、查詢余額接口（post 表單提交）
網關URL：https://router.wikeyun.cn/rest/User/query
數據格式：
{"code":"0000","msg":"獲取成功","data":{"money":"100","id":1234}}
三、油卡充值接口
1、添加充值卡
網關URL：https://router.wikeyun.cn/rest/Oil/addCard
| 參數名 |
類型 |
必填 |
參數說明 |
| store_id |
字符串 |
是 |
店鋪ID |
| card_num |
字符串 |
是 |
充值卡號 |
| name |
字符串 |
是 |
姓名 |
| phone |
字符串 |
是 |
手機號 |
| user_num |
字符串 |
是 |
身份證 |
| card_type |
整數 |
否 |
0中石化 1中石油 |
2、充值下單請求（post 表單提交）
網關URL：https://router.wikeyun.cn/rest/Oil/pushOrder
| 參數名 |
類型 |
必填 |
參數說明 |
| store_id |
字符串 |
是 |
店鋪ID |
| cardId |
整數 |
是 |
充值卡ID,來自創建接口 |
| order_no |
字符串 |
是 |
充值訂單號 |
| amount |
整數 |
是 |
充值金額（500） |
| recharge_type |
整型 |
是 |
1快充 0慢充，目前請傳0 |
| notify_url |
字符串 |
是 |
異步回調地址（POST） |
失敗返回數據格式：
{"code":"1003","msg":"app_key不能為空","time":"1624868000","data":null}
成功返回數據格式：
{"code":"0000","msg":"推送成功","data":{"order_number":"xxxx"}}
3、回調通知
| 參數名 |
類型 |
參數說明 |
| order_no |
字符串 |
充值訂單號 |
| order_number |
字符串 |
官方訂單號 |
| status |
字符串 |
交易結果（0 待支付 1 已付 充值中 2充值成功 3充值失敗 需要退款 4退款成功 6待充值 7 已匹配） |
收到回調后，商戶必須同步返回字符串 success，否則平台認為商戶沒有收到回調，會重復發送5
次回調。
4、查詢接口（post 表單提交）
網關URL：https://router.wikeyun.cn/rest/Oil/query
| 參數名 |
類型 |
必填 |
參數說明 |
| order_number |
字符串 |
是 |
官方訂單號 |
失敗返回數據格式：
{"code":"1003","msg":"app_key不能為空","time":"1624868000","data":null}
成功返回數據格式：
{"code":"0000","msg":"獲取成功","data":{"order_number":"xxxx","status":"1","mobile":"13786517891","amount":"100","order_no":"xxxx"}}
四、簽名算法
1、系統參數：
以下參數必須傳參，全部采用get傳參(拼接至url內)，系統參數包括：
| 參數名 |
類型 |
參數說明 |
| app_key |
字符串 |
應用唯一表示 |
| timestamp |
字符串 |
unix時間戳（秒單位） |
| client |
字符串 |
客戶端請求ip |
| v |
字符串 |
客戶端接口版本，目前是1.0 |
| format |
字符串 |
默認json |
| sign |
字符串 |
sign簽名 |
2、sign簽名算法
把業務參數+系統參數合並成一個數組，然后對數組進行ksort排序(按ASCII由小到大排序)，然后對合並后的數組進行循環拼接，格式如下：key1value1key2value2key3value3的形式拼接，最終首尾各拼接一個app_secret，對最終字符串進行md5大寫加密。
3、sign案例
然后對上面的url 進行post傳業務參數
附錄
1、充值請求code 狀態碼
| 0000 |
接口成功 |
| 1003 |
app_key不存在 |
| 1004 |
業務錯誤，具體看msg |
| 1005 |
sign簽名不對 |
| 1006 |
timestamp Out |
| 1007 |
應用已禁用 |
| 1008 |
余額不足 |
| 1009 |
相同面值太多,請拆分充值或者稍后再試 |
注意事項（話費快充）
1、請勿同一時間段推送大量訂單。
2、請勿推送大量相同面值的訂單，比如全是50，全是100，又或者50,100相間有規律的金額
3、系統會嚴格審核充值金額，同時出現多個金額相同的單子，就會返回1009失敗，請稍后再試或者拆分提交處理。