> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asynchronous Notifications

> Learn how to handle QFPay's payment and refund asynchronous notifications.

> [!NOTE]
>
> 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.

> [!TIP]
>
> It is strongly recommended to **verify** the status of a transaction using the [Transaction Enquiry API](https://sdk.qfapi.com/integration/common-api/transaction-enquiry.md) 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 Python theme={null}
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:**

```text theme={null}
A4021A3B1EBBB0F05451EF94E9EXXXXX
```

***

## Notification Response Example

```json theme={null}
{
  "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

| Field | Required | Type | Description |
| - | - | - | - |
| `status` | Yes | String | `1` = Payment Successful |
| `notify_type` | Yes | String | `payment` or `refund` |
| `pay_type` | Yes | String | QFPay payment code (see [Payment Types](https://sdk.qfapi.com/integration/api-reference/paytypes.md)) |
| `syssn` | Yes | String | QFPay Transaction Number |
| `out_trade_no` | Yes | String | Merchant Order Number |
| `txamt` | Yes | String | Amount in cents. Suggest value > 200 |
| `txcurrcd` | Yes | String | Transaction currency (see [Currencies](https://sdk.qfapi.com/integration/api-reference/currencies.md)) |
| `txdtm` | Yes | String | Merchant-side transaction time |
| `sysdtm` | Yes | String | System transaction time (used for settlement cutoff) |
| `paydtm` | Yes | String | Payment time |
| `cancel` | Yes | String | Cancellation status (see definitions below) |
| `respcd` | Yes | String | Always `0000` in async notifications |
| `mchid` | No | String | QFPay Merchant ID |
| `goods_name` | No | String | Product name |
| `goods_info` | No | String | Product description |
| `exchange_rate` | No | String | Currency exchange rate |
| `chnlsn` | No | String | Channel transaction number |
| `chnlsn2` | No | String | Additional channel reference |
| `cardcd` | No | String | Card number |
| `cash_fee` | No | String | Actual paid amount |
| `cash_fee_type` | No | String | Currency of `cash_fee` |
| `cash_refund_fee` | No | String | Actual refund amount |
| `cash_refund_fee_type` | No | String | Refund currency |

***

## Cancel Field Definitions

| Value | Meaning |
| - | - |
| 0 | Not Cancelled |
| 1 | **CPM:** Reversed or Refunded |
| 2 | **MPM:** Cancelled |
| 3 | Refunded |
| 4 | Preauth order completed (Alipay) |
| 5 | Partially Refunded |

***

## Notification IP Addresses

Ensure your server allows POST requests from:

* `13.228.112.115`
* `18.138.115.47`
* `18.166.202.92`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.