退款
大约 7 分鐘
統一退款
使用此接口針對成功支付發起退款，easylink支付網關會根據商戶發起的支付訂單號，找到對應到支付通道發起退款。退款可以是全額或部分。只要總退款金額小於或等於原始交易金額，一個交易可以有多個退款。
接口說明
請求URL：/api/refund/refundOrder
請求方式：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二者傳一即可 |
| 商戶退款單號 | mchRefundNo | 是 | String(30) | M27210632100491 | 商戶生成的退款單號 |
| 退款金額 | refundAmount | 是 | int | 100 | 退款金額,單位分 |
| 貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
| 退款原因 | refundReason | 是 | String(64) | 用戶退貨 | 退款原因 |
| 客戶端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客戶端IPV4地址 |
| 異步通知地址 | notifyUrl | 否 | String(128) | https://www.gnete.com.hk/notify.htm | 退款完成後回調該URL,只有傳了該值才會發起回調 |
| 渠道參數 | channelExtra | 否 | String(256) | {"auth_code", "13920933111042"} | 特定渠道發起的額外參數,json格式字符串.詳見渠道參數說明 |
| 擴展參數 | extraParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數,回調時會原樣返回 |
| 請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間,13位時間戳 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本號，固定：1.0 |
| 簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值，詳見簽名算法 |
| 簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型，目前只支持MD5方式 |
請求示例數據
{
"payOrderId": "P202106181104177050002",
"extParam": "",
"mchOrderNo": "",
"refundReason": "退款測試",
"sign": "2762CDB48D5179281DB6C0995E4EEDE0",
"reqTime": "1624007315",
"version": "1.0",
"channelExtra": "",
"appId": "60cc09bce4b0f1c0b83761c9",
"mchRefundNo": "mho1624007315478",
"clientIp": "192.166.1.132",
"notifyUrl": "https://www.gnete.com.hk/notify.html",
"signType": "MD5",
"currency": "HKD",
"mchNo": "M1623984572",
"refundAmount": 4
}返回參數
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回狀態 | code | 是 | int | 0 | 0-處理成功，其他-處理有誤，詳見錯誤碼 |
| 返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤 |
| 簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名,如data為空則不返回 |
| 返回數據 | data | 否 | String(512) | {} | 返回下單數據,json格式數據 |
data數據格式
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 退款訂單號 | refundOrderId | 是 | String(30) | R202106181708358940000 | 返回退款訂單號 |
| 商戶退款單號 | mchRefundNo | 是 | String(30) | mho1624007315478 | 返回商戶傳入的退款單號 |
| 退款狀態 | state | 是 | int | 2 | 退款狀態 0-訂單生成 1-退款中 2-退款成功 3-退款失敗 4-退款關閉 |
| 渠道退款單號 | channelOrderNo | 否 | String | 20160427210604000490 | 對應渠道的退款單號 |
| 渠道錯誤碼 | errCode | 否 | String | ACQ.PAYMENT_AUTH_CODE_INVALID | 上游渠道返回的錯誤碼 |
| 渠道錯誤描述 | errMsg | 否 | String | Business Failed 失敗 | 上游渠道返回的錯誤描述 |
返回示例數據
{
"code": 0,
"data": {
"channelOrderNo": "2021061822001423031419593035",
"mchRefundNo": "mho1624007315478",
"payAmount": 58,
"refundAmount": 4,
"refundOrderId": "R202106181708358940000",
"state": 2
},
"msg": "SUCCESS",
"sign": "2843B811B7A75D56B7D1950362820875"
}查詢訂單
商戶通過該接口查詢退款訂單，支付網關會返回訂單最新的數據
接口說明
請求URL：/api/refund/query
請求方式：POST
請求類型：application/json 或 application/x-www-form-urlencoded
請求參數
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
| 應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
| 退款訂單號 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款單號，與mchRefundNo二者傳一即可 |
| 商戶退款單號 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商戶生成的退款單號，與refundOrderId二者傳一即可 |
| 請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間,13位時間戳 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本號，固定：1.0 |
| 簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值，詳見簽名算法 |
| 簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型，目前只支持MD5方式 |
請求示例數據
{
"refundOrderId": "P202106181105527690009",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "1484293FCAEAFE11DEC8949DB6B525A9",
"signType": "MD5",
"reqTime": "1624008199",
"mchNo": "M1623984572",
"version": "1.0"
}| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回狀態 | code | 是 | int | 0 | 0-處理成功，其他-處理有誤，詳見錯誤碼 |
| 返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤 |
| 簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名，如data為空則不返回 |
| 返回數據 | data | 否 | String(512) | {} | 返回下單數據,json格式數據 |
data數據格式
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 退款訂單號 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款單號 |
| 支付訂單號 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系統訂單號 |
| 商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
| 應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
| 商戶退款單號 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商戶生成的退款單號 |
| 支付金額 | payAmount | 是 | int | 100 | 支付金額,單位分 |
| 退款金額 | refundAmount | 是 | int | 100 | 退款金額,單位分 |
| 貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
| 退款狀態 | state | 是 | int | 2 | 退款狀態 0-訂單生成 1-退款中 2-退款成功 3-退款失敗 4-退款關閉 |
| 渠道訂單號 | channelOrderNo | 否 | String | 20160427210604000490 | 對應渠道的訂單號 |
| 渠道錯誤碼 | errCode | 否 | String | 1002 | 渠道返回錯誤碼 |
| 渠道錯誤描述 | errMsg | 否 | String | 134586944573118714 | 渠道返回錯誤描述 |
| 擴展參數 | extraParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數,回調時會原樣返回 |
| 創建時間 | createdAt | 是 | long | 1622016572190 | 訂單創建時間,13位時間戳 |
| 成功時間 | successTime | 否 | long | 1622016572190 | 訂單支付成功時間,13位時間戳 |
返回示例數據
{
"code": 0,
"data": {
"appId": "60cc09bce4b0f1c0b83761c9",
"channelOrderNo": "2021061822001423031419593035",
"createdAt": 1623985552769,
"currency": "HKD",
"extParam": "",
"mchNo": "M1623984572",
"mchRefundNo": "mho1623985552430",
"payAmount": 58,
"payOrderId": "P202106181104177050002",
"refundAmount": 4,
"refundOrderId": "P202106181105527690009",
"state": 2,
"successTime": 1623985554000
},
"msg": "SUCCESS",
"sign": "E3F9F008FC5EF84BD782CCC7BE69DC5E"
}退款通知
當退款完成時（成功或失敗），支付網關會向商戶系統發起回調通知。如果商戶系統沒有正確返回，支付網關會延遲再次通知。
接口說明
請求URL：該鏈接是通過統一退款接口提交的參數notifyUrl設置，如果無法訪問鏈接，商戶系統將無法接收到支付中心的通知。
請求方式：POST
請求類型：application/x-www-form-urlencoded
通知參數
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 退款訂單號 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款單號 |
| 支付訂單號 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系統訂單號 |
| 商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
| 應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
| 商戶退款單號 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商戶生成的退款單號 |
| 支付金額 | payAmount | 是 | int | 100 | 支付金額,單位分 |
| 退款金額 | refundAmount | 是 | int | 100 | 退款金額,單位分 |
| 貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼,港幣:HKD |
| 退款狀態 | state | 是 | int | 2 | 退款狀態 0-訂單生成 1-退款中 2-退款成功 3-退款失敗 4-退款關閉 |
| 渠道訂單號 | channelOrderNo | 否 | String | 20160427210604000490 | 對應渠道的訂單號 |
| 渠道錯誤碼 | errCode | 否 | String | 1002 | 渠道返回錯誤碼 |
| 渠道錯誤描述 | errMsg | 否 | String | 134586944573118714 | 渠道返回錯誤描述 |
| 擴展參數 | extraParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數,回調時會原樣返回 |
| 創建時間 | createdAt | 是 | long | 1622016572190 | 訂單創建時間,13位時間戳 |
| 成功時間 | successTime | 否 | long | 1622016572190 | 訂單支付成功時間,13位時間戳 |
| 通知請求時間 | reqTime | 是 | String(30) | 1622016572190 | 通知請求時間，13位時間戳 |
| 簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值，詳見簽名算法 |
返回結果
業務系統處理後同步返回給支付中心，返回字符串 success 則表示成功，返回非success則表示處理失敗，支付中心會再次通知業務系統。（通知頻率為0/30/60/90/120/150,單位：秒）
注意：返回的字符串必須是小寫，且前後不能有空格和換行符。
通知示例數據
{
"appId": "60cc09bce4b0f1c0b83761c9",
"channelOrderNo": "2021061822001423031419593035",
"createdAt": 1623985552769,
"currency": "HKD",
"extParam": "",
"mchNo": "M1623984572",
"mchRefundNo": "mho1623985552430",
"payAmount": 58,
"payOrderId": "P202106181104177050002",
"refundAmount": 4,
"refundOrderId": "P202106181105527690009",
"state": 2,
"successTime": 1623985554000
}