Cancel
3/26/26About 5 min
Unified Cancel
The merchant cancels the order through this interface, and the payment gateway will process the cancellation of the completed order on the same day.
The following diagram shows the complete flow of canceling an order:
Flow Description:
- Merchant calls the cancel API to submit a cancel request
- Payment gateway initiates the cancel operation to the channel
- Channel returns the cancel processing result
- Payment gateway returns the result to the merchant
- If an async notification URL is configured, the payment gateway will send an additional async notification
Interface description
Request URL：/api/pay/cancel
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 | Order No. generated in the payment center, input either payOrderId or mchOrderNo |
| Merchant order No. | mchOrderNo | Yes | String(30) | 20160427210604000490 | Order No. generated by the merchant, input either payOrderId or mchOrderNo |
| 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 cancel is completed. A callback will only be initiated if this value is input |
| Channel extra | channelExtra | No | String(256) | {"auth_code", "13920933111042"} | Additional parameters initiated by a specific channel, in json format string. For details, see channel parameter description |
| Extended parameter | extParam | 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
{
"mchNo": "M1623984572",
"appId": "60cc09bce4b0f1c0b83761c9",
"payOrderId": "P202106181104177050002",
"mchOrderNo": "20160427210604000490",
"clientIp": "192.166.1.132",
"notifyUrl": "https://www.gnete.com.hk/notify.htm",
"channelExtra": "",
"extParam": "",
"reqTime": "1624006009",
"version": "1.0",
"sign": "46940C58B2F3AE426B77A297ABF4D31E",
"signType": "MD5"
}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 |
|---|---|---|---|---|---|
| Cancel order No. | cancelOrderId | Yes | String(30) | C202106181104177050002 | Return the cancel order No. |
| Cancel status | state | Yes | int | 2 | Cancel status 0-Order generated 1-Cancel in progress 2-Cancel success 3-Cancel failure 4-Cancel closed |
| Channel refund No. | channelOrderNo | No | String | 20160427210604000490 | Corresponding channel refund No. |
| Channel error code | errCode | No | String | 1002 | Error code returned by the channel |
| Channel error description | errMsg | No | String | Close exception | Error description returned by the channel |
Return example data
{
"code": 0,
"data": {
"cancelOrderId": "C202106181104177050002",
"state": 2,
"channelOrderNo": "2021061822001423031419593035",
"errCode": "",
"errMsg": ""
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}Order Query
Merchants query orders through this interface. The payment gateway will return the latest data of the order.
Interface description
Request URL：/api/cancel/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 |
| Cancel order No. | cancelOrderId | Yes | String(30) | C20160427210604000490 | Cancel order No. |
| 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
{
"cancelOrderId": "C202106181104177050002",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "46940C58B2F3AE426B77A297ABF4D31E",
"signType": "MD5",
"reqTime": "1624006009",
"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 |
|---|---|---|---|---|---|
| Cancel order No. | cancelOrderId | Yes | String(30) | C202106181104177050002 | Cancel order No. |
| Payment order No. | payOrderId | Yes | String(30) | P12021022311124442600 | Payment order No. |
| Merchant No. | mchNo | Yes | String(30) | M1621873433953 | Merchant No. |
| App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
| Payment amount | payAmount | Yes | long | 100 | Payment amount (unit: cents) |
| Currency code | currency | Yes | String(3) | HKD | Three-digit currency code: HKD |
| Cancel status | state | Yes | int | 2 | Cancel status 0-Order generated 1-Cancel in progress 2-Cancel success 3-Cancel failure 4-Cancel closed |
| Channel order No. | channelOrderNo | No | String | 20160427210604000490 | Channel order No. |
| Channel error code | errCode | No | String | 1002 | Channel error code |
| Channel error description | errMsg | No | String | Business error | Channel error description |
| Extended parameter | extraParam | No | String(512) | 134586944573118714 | Extended parameter |
| Order cancel success time | successTime | No | long | 1622016572190 | Order cancel success time, 13-digit timestamp |
| Created time | createdAt | Yes | long | 1622016572190 | Created time, 13-digit timestamp |
Return example data
{
"code": 0,
"data": {
"cancelOrderId": "C202106181104177050002",
"payOrderId": "P202106181104177050002",
"mchNo": "M1621873433953",
"appId": "60cc09bce4b0f1c0b83761c9",
"payAmount": 58,
"currency": "HKD",
"state": 2,
"channelOrderNo": "2021061822001423031419593035",
"errCode": "",
"errMsg": "",
"extraParam": "",
"successTime": 1623985554000,
"createdAt": 1623985552769
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}Cancel Notification
When the order is successfully cancelled, 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 cancel order 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 |
|---|---|---|---|---|---|
| Cancel order No. | cancelOrderId | Yes | String(30) | C202106181104177050002 | Cancel 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 |
| Amount of payment | payAmount | Yes | int | 100 | Amount of payment (unit: cents) |
| Currency code | currency | Yes | String(3) | HKD | Three-digit currency code: HKD |
| Cancel status | state | Yes | int | 2 | Cancel status 0-Order generated 1-Cancel in progress 2-Cancel success 3-Cancel failure 4-Cancel 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 is case-insensitive and there cannot be spaces or line breaks before or after the string.
Notification example data
{
"cancelOrderId": "C202106181104177050002",
"payOrderId": "P202106181104177050002",
"mchNo": "M1621873433953",
"appId": "60cc09bce4b0f1c0b83761c9",
"payAmount": 5,
"currency": "HKD",
"state": 2,
"channelOrderNo": "2021061822001423031419593035",
"errCode": "",
"errMsg": "",
"extraParam": "",
"createdAt": "1623985552769",
"successTime": "1623985554000",
"reqTime": "1623985554000",
"sign": "C380BEC2BFD727A4B6845133519F3AD6"
}