Refund
About 5 min
Unified refund
The merchant business system initiates a refund request through the unified refund interface. The easylink payment gateway will find the corresponding payment channel to initiate refund according to the payment order No. initiated by the merchant.The refund can be full or partial. A transaction can have multiple refunds as long as the total refund amount is less than or equal to the original transaction amount.
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 No. | mchNo | Yes | String(30) | M1621873433953 | Merchant No. |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Payment order No. | payOrderId | Yes | String(30) | P20160427210604000490 | Input either the order No. generated in the payment center or mchOrderNo |
| Merchant order No. | mchOrderNo | Yes | String(30) | 20160427210604000490 | Input either the order No. generated by the merchant or payOrderId |
| Merchant refund No. | mchRefundNo | Yes | String(30) | M27210632100491 | Refund No. generated by the merchant |
| Refund amount | refundAmount | Yes | int | 100 | Refund amount (unit: cents) |
| Currency code | currency | Yes | String(3) | HKD | Three-digit currency code: HKD |
| Refund reason | refundReason | Yes | String(64) | User return | Refund reason |
| Client IP | clientIp | No | String(32) | 210.73.10.148 | Client IPV4 address |
| Notify URL | notifyUrl | No | String(128) | https://www.gnete.com.hk/notify.htm | The URL is called back after the refund is completed. A callback will only be initiated if this value is input |
| Channel parameter | channelExtra | No | String(256 | {"auth_code", "13920933111042"} | Extra parameter initiated by a specific channel, in json format string. For details, see the channel parameter description |
| Extended parameter | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameter. It will be returned as it is during callback |
| Request time | reqTime | Yes | long | 1622016572190 | Request interface time, 13-digit timestamp |
| Interface version | version | Yes | String(3) | 1.0 | Interface version No., fixed: 1.0 |
| Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value. For details, see the 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
}Return parameters
| Field name | Variable name | Required | Type | Example value | Description |
|---|---|---|---|---|---|
| Return status | code | Yes | int | 0 | 0- Successful processing. Others - Processing error. For details, see the error code |
| Return message | msg | No | String(128) | Signature failed | Specific cause of error, for example, signature failed or parameter format verification error |
| Signature message | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Data signature. If data is empty, it will not be returned |
| Return data | data | No | String(512) | {} | Return the order placement data, in json format |
Data format
| Field name | Variable name | Required | Type | Example value | Description |
|---|---|---|---|---|---|
| Refund order No. | refundOrderId | Yes | String(30) | R202106181708358940000 | Return the refund order No. |
| Merchant refund No. | mchRefundNo | Yes | String(30) | mho1624007315478 | Return the refund No. input by the merchant |
| Refund status | state | Yes | int | 2 | Refund status 0-Order generated 1-Refund in progress 2-Refund success 3-Refund failure 4-Refund closure |
| Channel refund No. | channelOrderNo | No | String | 20160427210604000490 | Refund No. of corresponding channel |
| 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 |
Return example data
{
"code": 0,
"data": {
"channelOrderNo": "2021061822001423031419593035",
"mchRefundNo": "mho1624007315478",
"payAmount": 58,
"refundAmount": 4,
"refundOrderId": "R202106181708358940000",
"state": 2
},
"msg": "SUCCESS",
"sign": "2843B811B7A75D56B7D1950362820875"
}Order query
Merchants query refund orders through this interface. The payment gateway will return the latest data of 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 No. | mchNo | Yes | String(30) | M1621873433953 | Merchant No. |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Refund order No. | refundOrderId | Yes | String(30) | R20160427210604000490 | Input either the refund No. generated in the payment center or mchRefundNo |
| Merchant refund No. | mchRefundNo | Yes | String(30) | 20160427210604000490 | Input either the refund No. generated by the merchant or refundOrderId |
| Request time | reqTime | Yes | long | 1622016572190 | Request interface time, 13-digit timestamp |
| Interface version | version | Yes | String(3) | 1.0 | Interface version No., fixed: 1.0 |
| Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value. For details, see the signature algorithm |
| 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- Successful processing. Others - Processing error. For details, see the error code |
| Return message | msg | No | String(128) | Signature failed | Specific cause of error, for example, signature failed or parameter format verification error |
| Signature message | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Data signature. If data is empty, it will not be returned |
| Return data | data | No | String(512) | {} | Return the order placement data, in json format |
Data format
| Field name | Variable name | Required | Type | Example value | Description |
|---|---|---|---|---|---|
| Refund order No. | refundOrderId | Yes | String(30) | R20160427210604000490 | Refund No. generated in the payment center |
| Payment order No. | payOrderId | Yes | String(30) | P12021022311124442600 | Return the payment system order No. |
| Merchant No. | mchNo | Yes | String(30) | M1621873433953 | Merchant No. |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Merchant refund No. | mchRefundNo | Yes | String(30) | 20160427210604000490 | Refund No. generated by the merchant |
| Amount of payment | payAmount | Yes | int | 100 | Amount of payment (unit: cents) |
| Refund amount | refundAmount | Yes | int | 100 | Refund amount (unit: cents) |
| Currency code | currency | Yes | String(3) | HKD | Three-digit currency code: HKD |
| Refund status | state | Yes | int | 2 | Refund status 0-Order generated 1-Refund in progress 2-Refund success 3-Refund failure 4-Refund closure |
| Channel order No. | channelOrderNo | No | String | 20160427210604000490 | Order No. of corresponding channel |
| Channel error code | errCode | No | String | 1002 | Error code returned by the channel |
| Channel error description | errMsg | No | String | 134586944573118714 | Error description returned by the channel |
| Extended parameter | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameter. It will be returned as it is during callback |
| Created 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 the refund is completed (successfully or unsuccessfully), the payment gateway will send a callback notification to the merchant system. If the merchant system does not return correctly, the payment gateway will delay and send the notification again.
Interface description
Request URL：This link is set through the parameter notifyUrl submitted by the unified refund interface. If the link cannot be accessed, the merchant system will not be able to 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 No. | refundOrderId | Yes | String(30) | R20160427210604000490 | Refund No. generated in the payment center |
| Payment order No. | payOrderId | Yes | String(30) | P12021022311124442600 | Return the payment system order No. |
| Merchant No. | mchNo | Yes | String(30) | M1621873433953 | Merchant No. |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Merchant refund No. | mchRefundNo | Yes | String(30) | 20160427210604000490 | Refund No. generated by the merchant |
| Amount of payment | payAmount | Yes | int | 100 | Amount of payment (unit: cents) |
| Refund amount | refundAmount | Yes | int | 100 | Refund amount (unit: cents) |
| Currency code | currency | Yes | String(3) | HKD | Three-digit currency code: HKD |
| Refund status | state | Yes | int | 2 | Refund status 0-Order generated 1-Refund in progress 2-Refund success 3-Refund failure 4-Refund closure |
| Channel order No. | channelOrderNo | No | String | 20160427210604000490 | Order No. of corresponding channel |
| Channel error code | errCode | No | String | 1002 | Error code returned by the channel |
| Channel error description | errMsg | No | String | 134586944573118714 | Error description returned by the channel |
| Extended parameter | extraParam | No | String(512) | 134586944573118714 | Merchant extended parameter. It will be returned as it is during callback |
| Created 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. For details, see the signature algorithm |
Return result
After being processed by the business system, it is synchronously returned to the payment center. Returning the string "success" indicates success. Returning anything other than "success" indicates processing failure. The payment center will notify the business system again. (The notification frequency is 0/30/60/90/120/150s)
Note: The returned string must be in lowercase and there cannot be spaces or line breaks before or after the string.
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
}