Refund
Unified Refund
The merchant's business system initiates a refund request through the unified refund interface. The easylink payment gateway will find the corresponding payment channel based on the merchant's payment order number and initiate the refund.
Interface Description
Request URL: /api/refund/refundOrder
Request Method: POST
Request Type: application/json
or application/x-www-form-urlencoded
Request Parameters
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant Number |
App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
Payment Order Number | payOrderId | Yes | String(30) | P20160427210604000490 | Payment center generated order number, either this or mchOrderNo must be provided |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Merchant generated payment order number, either this or payOrderId must be provided |
Merchant Refund Number | mchRefundNo | Yes | String(30) | M27210632100491 | Merchant generated refund number |
Refund Amount | refundAmount | Yes | int | 100 | Refund amount, unit: cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, HKD for Hong Kong Dollar |
Refund Reason | refundReason | Yes | String(64) | User return | Refund reason |
Client IP | clientIp | No | String(32) | 210.73.10.148 | Client IPv4 address |
Asynchronous Notification URL | notifyUrl | No | String(128) | https://www.gnete.com.hk/notify.htm | URL for callback after refund completion, callback will only be made if this value is provided |
Channel Parameters | channelExtra | No | String(256) | {"auth_code", "13920933111042"} | Additional parameters for specific channels in JSON format. Refer to channel parameter description for details |
Extended Parameters | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameters, returned as-is in the callback |
Request Time | reqTime | Yes | long | 1622016572190 | Request time in milliseconds since epoch |
Interface Version | version | Yes | String(3) | 1.0 | Interface version number, fixed: 1.0 |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, refer to signature algorithm |
Signature Type | signType | Yes | String(32) | MD5 | Signature type, currently only MD5 is supported |
Request Example Data
{
"payOrderId": "P202106181104177050002",
"extParam": "",
"mchOrderNo": "",
"refundReason": "Refund test",
"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
}
Response Parameters
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Return Status | code | Yes | int | 0 | 0 - Processing successful, other - Processing error, see error codes for details |
Return Message | msg | No | String(128) | Signature failure | Specific error reason, e.g., signature failure, parameter format validation error |
Signature Information | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signature of the data inside, will not be returned if data is empty |
Return Data | data | No | String(512) | {} | Returned order data in JSON format |
data Data Format
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Refund Order Number | refundOrderId | Yes | String(30) | R202106181708358940000 | Returned refund order number |
Merchant Refund Number | mchRefundNo | Yes | String(30) | mho1624007315478 | Returned merchant provided refund number |
Refund Status | state | Yes | int | 2 | Refund status 0 - Order generated 1 - Refunding 2 - Refund successful 3 - Refund failed 4 - Refund closed |
Channel Refund Number | channelOrderNo | No | String | 20160427210604000490 | Channel's corresponding refund number |
Channel Error Code | errCode | No | String | ACQ.PAYMENT_AUTH_CODE_INVALID | Error code returned by upstream channel |
Channel Error Description | errMsg | No | String | Business Failed 失败 | Error description returned by upstream channel |
Response Example Data
{
"code": 0,
"data": {
"channelOrderNo": "2021061822001423031419593035",
"mchRefundNo": "mho1624007315478",
"payAmount": 58,
"refundAmount": 4,
"refundOrderId": "R202106181708358940000",
"state": 2
},
"msg": "SUCCESS",
"sign": "2843B811B7A75D56B7D1950362820875"
}
Query Order
Merchants use this interface to query refund orders. The payment gateway will return the latest data for the order.
Interface Description
Request URL: /api/refund/query
Request Method: POST
Request Type: application/json
or application/x-www-form-urlencoded
Request Parameters
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant Number |
App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
Refund Order Number | refundOrderId | Yes | String(30) | R20160427210604000490 | Refund order number generated by the payment center, either this or mchRefundNo must be provided |
Merchant Refund Number | mchRefundNo | Yes | String(30) | 20160427210604000490 | Merchant-generated refund number, either this or refundOrderId must be provided |
Request Time | reqTime | Yes | long | 1622016572190 | Request interface time, 13-digit timestamp |
Interface Version | version | Yes | String(3) | 1.0 | Interface version number, fixed: 1.0 |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see signature algorithm for details |
Signature Type | signType | Yes | String(32) | MD5 | Signature type, currently only MD5 is supported |
Request Example Data
{
"refundOrderId": "P202106181105527690009",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "1484293FCAEAFE11DEC8949DB6B525A9",
"signType": "MD5",
"reqTime": "1624008199",
"mchNo": "M1623984572",
"version": "1.0"
}
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Return Status | code | Yes | int | 0 | 0-Success, other values indicate errors, see error codes for details |
Return Message | msg | No | String(128) | Signature failure | Specific error reason, e.g., signature failure, parameter format validation error |
Signature Information | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signed information for the data, not returned if data is empty |
Return Data | data | No | String(512) | {} | Returned order data, in JSON format |
data Data Format
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Refund Order Number | refundOrderId | Yes | String(30) | R20160427210604000490 | Refund order number generated by the payment center |
Payment Order Number | payOrderId | Yes | String(30) | P12021022311124442600 | Returned payment system order number |
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant Number |
App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
Merchant Refund Number | mchRefundNo | Yes | String(30) | 20160427210604000490 | Merchant-generated refund number |
Payment Amount | payAmount | Yes | int | 100 | Payment amount, in cents |
Refund Amount | refundAmount | Yes | int | 100 | Refund amount, in cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, HKD for Hong Kong Dollar |
Refund Status | state | Yes | int | 2 | Refund status 0-Order Created 1-Refunding 2-Refund Successful 3-Refund Failed 4-Refund Closed |
Channel Order Number | channelOrderNo | No | String | 20160427210604000490 | Corresponding channel order number |
Channel Error Code | errCode | No | String | 1002 | Channel return error code |
Channel Error Description | errMsg | No | String | 134586944573118714 | Channel return error description |
Extended Parameters | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameters, will be returned as-is during callback |
Creation Time | createdAt | Yes | long | 1622016572190 | Order creation time, 13-digit timestamp |
Success Time | successTime | No | long | 1622016572190 | Order payment success time, 13-digit timestamp |
Return Example Data
{
"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"
}
Refund Notification
When a refund is completed (whether successful or failed), the payment gateway will send a callback notification to the merchant system. If the merchant system does not respond correctly, the payment gateway will delay and retry the notification.
Interface Description
Request URL: This link is specified by the notifyUrl
parameter submitted through the unified refund interface. If the link is not accessible, the merchant system will not receive notifications from the payment center.
Request Method: POST
Request Type: application/x-www-form-urlencoded
Notification Parameters
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Refund Order ID | refundOrderId | Yes | String(30) | R20160427210604000490 | Refund order number generated by the payment center |
Payment Order ID | payOrderId | Yes | String(30) | P12021022311124442600 | The payment system order number |
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
Application ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | Application ID |
Merchant Refund Order Number | mchRefundNo | Yes | String(30) | 20160427210604000490 | Refund order number generated by the merchant |
Payment Amount | payAmount | Yes | int | 100 | Payment amount, in cents |
Refund Amount | refundAmount | Yes | int | 100 | Refund amount, in cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, HKD for Hong Kong Dollar |
Refund Status | state | Yes | int | 2 | Refund status 0 - Order Generated 1 - Refund in Progress 2 - Refund Successful 3 - Refund Failed 4 - Refund Closed |
Channel Order Number | channelOrderNo | No | String | 20160427210604000490 | Channel's corresponding order number |
Channel Error Code | errCode | No | String | 1002 | Channel return error code |
Channel Error Description | errMsg | No | String | 134586944573118714 | Channel return error description |
Extended Parameters | extraParam | No | String(512) | 134586944573118714 | Merchant's extended parameters, returned as-is in the callback |
Creation Time | createdAt | Yes | long | 1622016572190 | Order creation time, 13-digit timestamp |
Success Time | successTime | No | long | 1622016572190 | Order payment success time, 13-digit timestamp |
Notification Request Time | reqTime | Yes | String(30) | 1622016572190 | Notification request time, 13-digit timestamp |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see signature algorithm for details |
Return Result
After processing, the business system synchronously returns a response to the payment center. Returning the string success
indicates success, while returning anything other than success
indicates failure. The payment center will retry notifying the business system. (Notification frequency is 0/30/60/90/120/150 seconds)
Note: The returned string must be in lowercase and cannot contain leading or trailing spaces or line breaks.
Notification Example 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
}