Supported Scenarios
The
/trade/v1/reversal API is currently only supported in the following scenarios. It applies to transactions in a non-completed state (e.g. scanned but not paid).Supported payment flows and PayTypes
Alipay MPM (Merchant Presented Mode)800101:Alipay Merchant Presented QR Code Payment in store (MPM) (Overseas Merchants)801501:Alipay Merchant Presented QR Code (MPM) Payment (HK Merchants)
800201:WeChat Merchant Presented QR Code Payment (MPM) (Overseas & HK Merchants)
800108:Alipay Consumer Presented QR Code Payment (CPM) (Overseas & HK Merchants)
For cancellations involving other wallets, please refer to the Close API or contact QFPay Support for integration guidance.
API Endpoint
- Endpoint:
/trade/v1/reversal - Method:
POST
respcd=0000.
If the transaction has already completed successfully (respcd=0000 in payment), then it cannot be reversed. Instead, refer to the Refund API.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
mchid | String(16) | No | QFPay Merchant ID. Required only for agents. |
syssn | String(40) | Yes* | QFPay transaction number |
out_trade_no | String(128) | Yes* | Merchant transaction number |
txamt | Int(11) | Yes | Transaction amount in cents (e.g. 100 = $1). Suggest value > 200. |
txdtm | String(20) | Yes | Original transaction time. Format: YYYY-MM-DD hh:mm:ss |
udid | String(40) | No | Unique terminal ID (used for traceability) |
*Eithersyssnorout_trade_nomust be provided.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
syssn | String | New QFPay transaction number for the reversal |
orig_syssn | String | QFPay transaction number of the original (to-be-reversed) transaction |
txamt | Int | Reversed amount (in cents) |
txcurrcd | String(3) | Currency code, e.g. HKD |
txdtm | String | Transaction time |
sysdtm | String | QFPay system time of the reversal |
chnlsn | String | Payment channel transaction number (may be empty if not processed) |
respcd | String(4) | Response code (0000 = success, others = failure or in progress) |
resperr | String | Result message |
respmsg | String | Additional description (if any) |
Code Examples
Sample Response
JSON
Additional Notes
- A reversal does not guarantee that the user has not been charged. Always verify using Transaction Enquiry.
- Reversal is intended for real-time failures only. Do not use it to refund successful transactions.
- If
respcd=1143or1145, the reversal is in progress. You should poll the Transaction Enquiry endpoint until the status is confirmed.
The above command returns JSON structured like this:
JSON
Reversal vs Close
Some wallets (e.g. WeChat Pay MPM) support the/trade/v1/close endpoint instead of reversal.
Supported payment flows and PayTypes
WeChat Pay CPM (Consumer Presented Mode)800008:Consumer Present QR Code Mode (CPM) for WeChat800208:WeChat Consumer Presented QR Code Payment (CPM) (Overseas & HK Merchants)801008:WeChat Pay HK Consumer Presented QR Code Payment (CPM) (Direct Settlement, HK Merchants)
GET
*If you would like to use this endpoint on a wallet other than Alipay & Wechat Pay please contact us for instructions.
Request Parameters
| Attribute | Mandatory | Type | Description |
|---|---|---|---|
mchid | No | String(16) | Merchant ID allocated by QFPay |
syssn | Yes* | String(40) | QFPay transaction number, returned by the system once payment is completed |
out_trade_no | Yes* | String(128) | External transaction number |
txamt | Yes | Int(11) | Amount of the transaction. Unit in cents (i.e. 100 = $1). Suggest value > 200 to avoid risk control. |
txdtm | Yes | String(20) | Transaction time format: YYYY-MM-DD hh:mm:ss |
udid | No | String(40) | Unique transaction device ID. Is displayed on the merchant portal. |
syssn or out_trade_no must be provided.
Response Parameters
| Attribute | Type | Description |
|---|---|---|
orig_syssn | String(40) | Refers to the original QFPay transaction number |
syssn | String(40) | QFPay transaction number of the cancel/ reversal |
out_trade_no | String(128) | External transaction number |
txamt | Int(11) | Amount of the transaction. Unit in cents (i.e. 100 = $1) |
txcurrcd | String(3) | Transaction currency. View the Currencies table for a complete list of available currencies |
txdtm | String(20) | Transaction time. Format: YYYY-MM-DD hh:mm:ss |
sysdtm | String(20) | System transaction time. Format: YYYY-MM-DD hh:mm:ss This parameter value is used as the cut-off time for settlements. |
chnlsn | String | Transaction number from payment channel (wallet side) |
respcd | String(4) | Response code 0000 = Reversal/ cancel successul 1143/1145 = Reversal/ cancel in progress others = Reversal/ cancel failed |
resperr | String(128) | Result description |
respmsg | String(128) | Information description |
