Skip to main content
To configure your notification URL, please send your endpoint address along with your merchant and store information to technical.support@qfpay.com.
QFPay supports asynchronous notifications for:
  • Payments ("notify_type": "payment")
  • Refunds ("notify_type": "refund")
These notifications allow merchants to receive real-time updates on transaction results. Since parameters may expand in future versions, your integration should be able to gracefully handle unknown fields.

​
Overview

When a payment or refund is completed, QFPay will POST a JSON-formatted notification to the merchant-defined callback URL.
It is strongly recommended to verify the status of a transaction using the Transaction Enquiry API in addition to handling the callback.

​
Notification Rules

  1. Only successful payments and refunds will trigger a notification.
  2. Please register your notification endpoint via email to technical.support@qfpay.com. Our team will configure it for you.
  3. Merchants must validate the notification using the signature verification process below. After successful verification, return:
    • HTTP Status Code: 200 OK
    • Response Body: SUCCESS
  4. If the expected response is not received, QFPay will retry the callback at the following intervals:
    • 2 minutes → 10 minutes → 10 minutes → 60 minutes → 2 hours → 6 hours → 15 hours
    • Retry stops after receiving 200 OK and SUCCESS
  5. One app_code + client_key pair can only be bound to one notification URL. Agents should use a shared endpoint for sub-merchants.
  6. Method: POST
    Content-Type: application/json
    Allowed Ports: 80 and 443 only (for security)

​
Signature Verification

The verification process differs from regular API requests.

​
Steps

  1. Extract the value from the X-QF-SIGN header.
  2. Concatenate the raw request body (JSON string) + your client_key.
  3. Generate an MD5 hash of this combined string.
  4. If the hash matches the X-QF-SIGN value, the message is valid. Return 200 OK with body SUCCESS.

​
Signature Example

Python
import hashlib
import json

# Client Credentials
client_key = "3ABB1BFFE2E0497BB9270978B0BXXXXX"

# Raw Content Data
data = {
    "status": "1",
    "pay_type": "800101",
    "sysdtm": "2020-06-15 10:32:58",
    "paydtm": "2020-06-15 10:33:35",
    "goods_name": "",
    "txcurrcd": "HKD",
    "txdtm": "2020-06-15 10:32:58",
    "mchid": "O37MRh6Qq5",
    "txamt": "10",
    "exchange_rate": "",
    "chnlsn2": "",
    "out_trade_no": "9G3ZIWTG1R3IVSC2AH2O5EGKJQ7I72QO",
    "syssn": "20200615000200020000641807",
    "cash_fee_type": "",
    "cancel": "0",
    "respcd": "0000",
    "goods_info": "",
    "cash_fee": "0",
    "notify_type": "payment",
    "chnlsn": "2020061522001453561406303428",
    "cardcd": "2088032341453564"
}

combine_str = (json.dumps(data) + client_key).encode()
signature = hashlib.md5(combine_str).hexdigest().upper()

print(signature)
Sample Signature Output: 
A4021A3B1EBBB0F05451EF94E9EXXXXX

​
Notification Response Example

{
  "status": "1",
  "pay_type": "800101",
  "sysdtm": "2020-05-14 12:32:56",
  "paydtm": "2020-05-14 12:33:56",
  "goods_name": "",
  "txcurrcd": "HKD",
  "txdtm": "2020-05-14 12:32:56",
  "mchid": "lkbqahlRYj",
  "txamt": "10",
  "exchange_rate": "",
  "chnlsn2": "",
  "out_trade_no": "YEPE7WTW46NVU30JW5N90H7DHD94N56B",
  "syssn": "20200514000300020093755455",
  "cash_fee_type": "",
  "cancel": "0",
  "respcd": "0000",
  "goods_info": "",
  "cash_fee": "0",
  "notify_type": "payment",
  "chnlsn": "2020051422001453561444935817",
  "cardcd": "2088032341453564"
}

​
Response Field Reference

FieldRequiredTypeDescription
statusYesString1 = Payment Successful
notify_typeYesStringpayment or refund
pay_typeYesStringQFPay payment code (see Payment Types)
syssnYesStringQFPay Transaction Number
out_trade_noYesStringMerchant Order Number
txamtYesStringAmount in cents. Suggest value > 200
txcurrcdYesStringTransaction currency (see Currencies)
txdtmYesStringMerchant-side transaction time
sysdtmYesStringSystem transaction time (used for settlement cutoff)
paydtmYesStringPayment time
cancelYesStringCancellation status (see definitions below)
respcdYesStringAlways 0000 in async notifications
mchidNoStringQFPay Merchant ID
goods_nameNoStringProduct name
goods_infoNoStringProduct description
exchange_rateNoStringCurrency exchange rate
chnlsnNoStringChannel transaction number
chnlsn2NoStringAdditional channel reference
cardcdNoStringCard number
cash_feeNoStringActual paid amount
cash_fee_typeNoStringCurrency of cash_fee
cash_refund_feeNoStringActual refund amount
cash_refund_fee_typeNoStringRefund currency

​
Cancel Field Definitions

ValueMeaning
0Not Cancelled
1CPM: Reversed or Refunded
2MPM: Cancelled
3Refunded
4Preauth order completed (Alipay)
5Partially Refunded

​
Notification IP Addresses

Ensure your server allows POST requests from:
  • 13.228.112.115
  • 18.138.115.47
  • 18.166.202.92