> ## 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.

# Transaction Enquiry

> Query the status of payments, refunds, and cancellations via QFPay's transaction enquiry API.

After making a payment, refund, or cancellation request, merchants can use the transaction enquiry API to retrieve the latest transaction status.

This API supports querying by:

* `syssn` (QFPay transaction number)
* `out_trade_no` (merchant-side order number)
* `start_time` / `end_time` (time-based filtering)

If querying a refund transaction, the response will also return `origssn`, which refers to the original transaction’s `syssn`.

***

## HTTP Request

* **Endpoint**: `/trade/v1/query`
* **Method**: `POST`

### Request Headers

```http HTTP theme={null}
Content-Type: application/x-www-form-urlencoded
X-QF-APPCODE: <your-app-code>
X-QF-SIGN: <signature>
```

***

## Request Parameters

Full details are documented in [Common API Request Format](/integration/api-reference/request-format). Key parameters include:

| Parameter      | Type        | Required    | Description                                                      |
| -------------- | ----------- | ----------- | ---------------------------------------------------------------- |
| `mchid`        | String(16)  | Conditional | Required if assigned to the merchant.                            |
| `syssn`        | String(128) | No          | QFPay transaction number(s), comma-separated.                    |
| `out_trade_no` | String(128) | No          | Merchant order number(s), comma-separated.                       |
| `pay_type`     | String(6)   | No          | Payment type(s), comma-separated.                                |
| `respcd`       | String(4)   | No          | Filter by specific response code (e.g. `0000`).                  |
| `start_time`   | String(20)  | No          | Format: `YYYY-MM-DD hh:mm:ss`. Required for cross-month queries. |
| `end_time`     | String(20)  | No          | Format: `YYYY-MM-DD hh:mm:ss`. Required for cross-month queries. |
| `page`         | Integer     | No          | Default = 1.                                                     |
| `page_size`    | Integer     | No          | Default = 10. Max = 100.                                         |

<Note>
  For cross-month queries, `start_time` and `end_time` are required.
</Note>

***

## Example Request Body

```http Form Example theme={null}
mchid=<merchant-id>&syssn=<qfpay-tx-id>&start_time=2022-12-01 00:00:00&end_time=2022-12-01 23:59:59
```

***

## Sample Code (Multi-language)

<CodeGroup>
  ```python Python theme={null}
  import hashlib
  import requests

  environment = 'https://test-openapi-hk.qfapi.com'
  app_code = 'D5589D2A1F2E42A9A60C37**********'
  client_key = '0E32A59A8B454940A2FF39**********'

  def make_req_sign(data, key):
      keys = sorted(data.keys())
      parts = []
      for k in keys:
          parts.append(f"{k}={data[k]}")
      unsign_str = ("&".join(parts) + key).encode("utf-8")
      return hashlib.md5(unsign_str).hexdigest().upper()

  data = {
      'mchid': 'ZaMVg*****',
      'syssn': '20191227000200020061752831'
  }

  sign = make_req_sign(data, client_key)

  r = requests.post(
      environment + "/trade/v1/query",
      data=data,
      headers={
          'X-QF-APPCODE': app_code,
          'X-QF-SIGN': sign
      }
  )

  print(sign)
  print(r.json())
  ```

  ```java Java theme={null}
  import java.util.HashMap;
  import java.util.Map;

  public class Enquiry {
      public static void main(String[] args) {
          String appcode = "D5589D2A1F2E42A9A60C37**********";
          String key = "0E32A59A8B454940A2FF39*********";
          String mchid = "ZaMVg*****";

          String syssn = "20191227000300020061662295";

          Map<String, String> params = new HashMap<>();
          params.put("mchid", mchid);
          params.put("syssn", syssn);

          String data = QFPayUtils.getDataString(params);
          String md5Sum = QFPayUtils.getMd5Value(data + key);

          String url = "https://test-openapi-hk.qfapi.com";
          String resp = Requests.sendPostRequest(url + "/trade/v1/query", data, appcode, md5Sum);
          System.out.println(resp);
      }
  }
  ```

  ```javascript Node.js theme={null}
  const crypto = require('crypto');
  const request = require('request');

  const environment = 'https://test-openapi-hk.qfapi.com';
  const app_code = 'D5589D2A1F2E42A9A60C37**********';
  const client_key = '0E32A59A8B454940A2FF39**********';

  const payload = {
    syssn: '20191231000300020063521806',
    start_time: '2019-12-27 00:00:00',
    end_time: '2019-12-31 23:59:59',
    mchid: 'ZaMVg*****'
  };

  const ordered = {};
  Object.keys(payload).sort().forEach(k => ordered[k] = payload[k]);

  const str = Object.keys(ordered)
    .map(k => `${k}=${ordered[k]}`)
    .join('&') + client_key;

  const sign = crypto.createHash('md5')
    .update(str)
    .digest('hex')
    .toUpperCase();

  request({
    uri: environment + "/trade/v1/query",
    headers: { 'X-QF-APPCODE': app_code, 'X-QF-SIGN': sign },
    method: "POST",
    form: payload
  }, (error, response, body) => {
    console.log(body);
  });
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://test-openapi-hk.qfapi.com';
  $api_type = '/trade/v1/query';

  $app_code = 'FF2FF74F2F2E42769A4A73*********';
  $app_key  = '7BE791E0FD2E48E6926043B*********';

  $fields = array(
    'syssn' => '20200311066100020000977841'
  );

  ksort($fields);

  $fields_string = '';
  foreach ($fields as $k => $v) {
    $fields_string .= $k.'='.urlencode($v).'&';
  }
  $fields_string = rtrim($fields_string, '&');

  $sign = strtoupper(md5($fields_string . $app_key));

  $header = array(
    'X-QF-APPCODE: ' . $app_code,
    'X-QF-SIGN: ' . $sign
  );

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url . $api_type);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);

  $output = curl_exec($ch);
  curl_close($ch);

  echo $output;
  ?>
  ```
</CodeGroup>

***

## Sample Response

```json JSON theme={null}
{
  "respcd": "0000",
  "resperr": "Request successful",
  "data": [
    {
      "syssn": "20230423000200020088888888",
      "out_trade_no": "YOUR_ORDER_001",
      "txamt": "100",
      "txcurrcd": "HKD",
      "respcd": "0000",
      "errmsg": "success",
      "pay_type": "801107",
	  "note": "reference txn note",
      "order_type": "payment",
      "txdtm": "2023-04-23 12:00:00",
      "sysdtm": "2023-04-23 12:00:03",
      "cancel": "0",
      "cash_fee": "100",
      "cash_fee_type": "HKD"
    }
  ]
}
```