支付
統一下單
商戶業務系統通過統一下單接口發起支付收款訂單,easylink支付網關會根據商戶配置的支付通道路由支付通道完成支付下單。支付網關根據不同的支付方式返回對應的支付參數,業務系統使用支付參數發起收款。
接口說明
請求URL:/api/pay/unifiedOrder
請求方式:POST
請求類型:application/json
或 application/x-www-form-urlencoded
請求參數
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商戶生成的訂單號 |
支付方式 | wayCode | 是 | String(30) | WX_LITE | 支付方式,如微信小程序WX_LITE |
支付金額 | amount | 是 | int | 100 | 支付金額, 單位分 |
貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
客戶端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客戶端IPV4地址 |
商品標題 | subject | 是 | String(64) | 商品標題測試 | 商品標題 |
商品描述 | body | 是 | String(256) | 商品描述測試 | 商品描述 |
異步通知地址 | notifyUrl | 否 | String(128) | https://www.gnete.com.hk/notify.htm | 支付結果異步回調URL,只有傳了該值才會發起回調 |
跳轉通知地址 | returnUrl | 否 | String(128) | https://www.gnete.com.hk/return.htm | 支付結果同步跳轉通知URL |
失效時間 | expiredTime | 否 | int | 3600 | 訂單失效時間, 單位秒, 默認2小時. 訂單在(創建時間+失效時間)後失效 |
渠道參數 | channelExtra | 否 | String(256) | {"auth_code", "13920933111042"} | 特定渠道發起的額外參數, json格式字符串. 詳見渠道參數說明 |
擴展參數 | extParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數, 回調時會原樣返回 |
請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間, 13位時間戳 |
接口版本 | version | 是 | String(3) | 1.0 | 接口版本號,固定:1.0 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值,詳見簽名算法 |
簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型,目前只支持MD5方式 |
請求示例數據
{
"amount": 8,
"extParam": "",
"mchOrderNo": "mho1624005107281",
"subject": "商品標題",
"wayCode": "WX_H5",
"sign": "84F606FA25A6EC4783BECC08D4FDC681",
"reqTime": "1624005107",
"body": "商品描述",
"version": "1.0",
"channelExtra": "{\"authCode\":\"280812820366966512\"}",
"appId": "60cc09bce4b0f1c0b83761c9",
"clientIp": "192.166.1.132",
"notifyUrl": "https://www.gnete.com.hk/notify.html",
"signType": "MD5",
"currency": "HKD",
"returnUrl": "",
"mchNo": "M1623984572"
}
返回參數
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回狀態 | code | 是 | int | 0 | 0-處理成功,其他-處理有誤,詳見錯誤碼 |
返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因,例如:簽名失敗、參數格式校驗錯誤 |
簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名,如data為空則不返回 |
返回數據 | data | 否 | String(512) | {} | 返回下單數據, json格式數據 |
data數據格式
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
支付訂單號 | payOrderId | 是 | String(30) | U12021022311124442600 | 返回支付系統訂單號 |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 返回商戶傳入的訂單號 |
訂單狀態 | orderState | 是 | int | 2 | 支付訂單狀態 0-訂單生成 1-支付中 2-支付成功 3-支付失敗 4-已撤銷 5-已退款 6-訂單關閉 |
支付數據類型 | payDataType | 是 | String | payUrl | 支付參數類型 payUrl-跳轉鏈接的方式 form-表單方式 wxapp-微信支付參數(微信公眾號, 小程序, app支付時) aliapp-支付寶app支付參數 ysfapp-雲閃付app支付參數 codeUrl-二維碼地址 codeImgUrl-二維碼圖片地址 none-空支付參數 |
支付數據 | payData | 否 | String | http://www.gnete.com.hk/pay.html | 發起支付用到的支付參數,如果微信公眾號支付等 |
渠道錯誤碼 | errCode | 否 | String | ACQ.PAYMENT_AUTH_CODE_INVALID | 上游渠道返回的錯誤碼 |
渠道錯誤描述 | errMsg | 否 | String | Business Failed 失敗 | 上游渠道返回的錯誤描述 |
返回示例數據
{
"code": 0,
"data": {
"errCode": "ACQ.PAYMENT_AUTH_CODE_INVALID",
"errMsg": "Business Failed【支付失敗,獲取顧客賬戶信息失敗,請顧客刷新付款碼後重新收款,如再次收款失敗,請聯繫管理員處理。[SOUNDWAVE_PARSER_FAIL]】",
"mchOrderNo": "mho1624005752661",
"orderState": 3,
"payOrderId": "P202106181642329900002"
},
"msg": "SUCCESS",
"sign": "F4DA202C516D1F33A12F1E547C5004FD"
}
支付方式
WayCode | 支付方式 |
---|---|
ALI_JSAPI | 支付寶生活號 |
ALI_APP | 支付寶APP |
ALI_H5 | 支付寶H5 |
ALI_QR | 支付寶掃碼(主掃) |
WX_JSAPI | 微信公眾號 |
WX_LITE | 微信小程序 |
WX_APP | 微信APP |
WX_H5 | 微信H5 |
WX_QR | 微信掃碼(主掃) |
UP_OP | 銀聯在線支付 |
UP_APP | 銀聯APP |
YSF_QR | 雲閃付掃碼(主掃) |
NUVEI_H5 | NUVEI H5 |
channelExtra參數說明
當 wayCode=WX_JSAPI
或 wayCode=WX_LITE
時,channelExtra必須傳subAppid、openid,channelExtra示例數據如:
{"subAppid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI", "openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
當 wayCode=WX_H5
或 wayCode=WX_APP
時,channelExtra可以傳subAppid,channelExtra示例數據如:
{"appid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
當 wayCode=ALI_QR
或 wayCode=WX_QR
或 wayCode=YSF_QR
時,channelExtra可以傳payDataType設置返回支付數據支付類型。此時payDataType可以為:codeUrl-二維碼地址,codeImgUrl-二維碼圖片地址,不傳payDataType默認返回codeUrl類型, channelExtra示例數據如:
{"payDataType": "codeImgUrl"}
當 wayCode=UP_OP
或 wayCode=UP_APP
時,channelExtra可以傳accNo鎖定銀行卡號交易。channelExtra示例數據如:
{"accNo": "6222222222222222"}
查詢訂單
商戶通過該接口查詢訂單,支付網關會返回訂單最新的數據
接口說明
請求URL:/api/pay/query
請求方式:POST
請求類型:application/json
或 application/x-www-form-urlencoded
請求參數
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
支付訂單號 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的訂單號,與mchOrderNo二者傳一即可 |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商戶生成的訂單號,與payOrderId二者傳一即可 |
請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間,13位時間戳 |
接口版本 | version | 是 | String(3) | 1.0 | 接口版本號,固定:1.0 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值,詳見簽名算法 |
簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型,目前只支持MD5方式 |
請求示例數據
{
"payOrderId": "P202106181104177050002",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "46940C58B2F3AE426B77A297ABF4D31E",
"signType": "MD5",
"reqTime": "1624006009",
"mchNo": "M1623984572",
"version": "1.0"
}
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回狀態 | code | 是 | int | 0 | 0-處理成功,其他-處理有誤,詳見錯誤碼 |
返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因,例如:簽名失敗、參數格式校驗錯誤 |
簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名,如data為空則不返回 |
返回數據 | data | 否 | String(512) | {} | 返回下單數據,json格式數據 |
data數據格式
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
支付訂單號 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系統訂單號 |
商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 返回商戶傳入的訂單號 |
支付接口 | ifCode | 是 | String(30) | wxpay | 支付接口編碼 |
支付方式 | wayCode | 是 | String(30) | WX_LITE | 支付方式,如微信小程序WX_LITE |
支付金額 | amount | 是 | int | 100 | 支付金額,單位分 |
貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
訂單狀態 | state | 是 | int | 2 | 支付訂單狀態 0-訂單生成 1-支付中 2-支付成功 3-支付失敗 4-已撤銷 5-已退款 6-訂單關閉 |
客戶端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客戶端IPV4地址 |
商品標題 | subject | 是 | String(64) | 商品標題測試 | 商品標題 |
商品描述 | body | 是 | String(256) | 商品描述測試 | 商品描述 |
渠道訂單號 | channelOrderNo | 否 | String | 20160427210604000490 | 對應渠道的訂單號 |
渠道錯誤碼 | errCode | 否 | String | 1002 | 渠道下單返回錯誤碼 |
渠道錯誤描述 | errMsg | 否 | String | 業務異常錯誤 | 渠道下單返回錯誤描述 |
擴展參數 | extParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數,回調時會原樣返回 |
創建時間 | createdAt | 是 | long | 1622016572190 | 訂單創建時間,13位時間戳 |
成功時間 | successTime | 否 | long | 1622016572190 | 訂單支付成功時間,13位時間戳 |
返回示例數據
{
"code": 0,
"data": {
"amount": 58,
"appId": "60cc09bce4b0f1c0b83761c9",
"body": "商品描述",
"channelOrderNo": "2021061822001423031419593035",
"clientIp": "192.166.1.132",
"createdAt": 1623985457705,
"currency": "HKD",
"extParam": "",
"ifCode": "alipay",
"mchNo": "M1623984572",
"mchOrderNo": "mho1623985457320",
"payOrderId": "P202106181104177050002",
"state": 2,
"subject": "商品標題",
"successTime": 1623985459000,
"wayCode": "WX_H5"
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}
關閉訂單
商戶通過該接口關閉訂單,支付網關會對訂單完成關閉處理。
接口說明
請求URL:/api/pay/close
請求方式:POST
請求類型:application/json
或 application/x-www-form-urlencoded
請求參數
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
支付訂單號 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的訂單號,與mchOrderNo二者傳一即可 |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商戶生成的訂單號,與payOrderId二者傳一即可 |
請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間,13位時間戳 |
接口版本 | version | 是 | String(3) | 1.0 | 接口版本號,固定:1.0 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值,詳見簽名算法 |
簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型,目前只支持MD5方式 |
請求示例數據
{
"payOrderId": "P202106181104177050002",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "46940C58B2F3AE426B77A297ABF4D31E",
"signType": "MD5",
"reqTime": "1624006009",
"mchNo": "M1623984572",
"version": "1.0"
}
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回狀態 | code | 是 | int | 0 | 0-處理成功,其他-處理有誤,詳見錯誤碼 |
返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因,例如:簽名失敗、參數格式校驗錯誤 |
簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名,如data為空則不返回 |
返回數據 | data | 否 | String(512) | {} | 返回下單數據,json格式數據 |
data數據格式
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
渠道錯誤碼 | errCode | 否 | String | 1002 | 渠道關單返回錯誤碼 |
渠道錯誤描述 | errMsg | 否 | String | 關閉異常 | 渠道關單返回錯誤描述 |
返回示例數據
{
"code": 0,
"data": {
"errCode": "",
"errMsg": ""
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}
支付通知
當訂單支付成功時,支付網關會向商戶系統發起回調通知。如果商戶系統沒有正確返回,支付網關會延遲再次通知。
接口說明
請求URL:該鏈接是通過統一下單接口提交的參數notifyUrl設置,如果無法訪問鏈接,商戶系統將無法接收到支付中心的通知。
請求方式:POST
請求類型:application/x-www-form-urlencoded
通知參數
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
支付訂單號 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系統訂單號 |
商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 返回商戶傳入的訂單號 |
支付接口 | ifCode | 是 | String(30) | wxpay | 支付接口編碼 |
支付方式 | wayCode | 是 | String(30) | WX_LITE | 支付方式,微信小程序WX_LITE |
支付金額 | amount | 是 | int | 100 | 支付金額,單位分 |
貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
訂單狀態 | state | 是 | int | 2 | 支付訂單狀態 0-訂單生成 1-支付中 2-支付成功 3-支付失敗 4-已撤銷 5-已退款 6-訂單關閉 |
客戶端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客戶端IPV4地址 |
商品標題 | subject | 是 | String(64) | 商品標題測試 | 商品標題 |
商品描述 | body | 是 | String(256) | 商品描述測試 | 商品描述 |
渠道訂單號 | channelOrderNo | 否 | String | 20160427210604000490 | 對應渠道的訂單號 |
渠道錯誤碼 | errCode | 否 | String | 1002 | 渠道下單返回錯誤碼 |
渠道錯誤描述 | errMsg | 否 | String | 134586944573118714 | 渠道下單返回錯誤描述 |
擴展參數 | extParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數 |
創建時間 | createdAt | 是 | long | 1622016572190 | 訂單創建時間,13位時間戳 |
成功時間 | successTime | 否 | long | 1622016572190 | 訂單支付成功時間,13位時間戳 |
通知請求時間 | reqTime | 是 | long | 1622016572190 | 通知請求時間,13位時間戳 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值,詳見簽名算法 |
返回結果
業務系統處理後同步返回給支付中心,返回字符串 success 則表示成功,返回非success則表示處理失敗,支付中心會再次通知業務系統。(通知頻率為0/30/60/90/120/150,單位:秒)
注意:返回的字符串不區分大小寫,字符串前後不能有空格和換行符。
通知示例數據
{
"amount": 5,
"body": "商品描述",
"clientIp": "192.166.1.132",
"createdAt": "1622016572190",
"currency": "HKD",
"extParam": "",
"ifCode": "wxpay",
"mchNo": "M1621873433953",
"appId": "60cc09bce4b0f1c0b83761c9",
"mchOrderNo": "mho1621934803068",
"payOrderId": "20210525172643357010",
"state": 3,
"subject": "商品標題",
"wayCode": "WX_H5",
"sign": "C380BEC2BFD727A4B6845133519F3AD6"
}