HONGKONG-PAYMENT-QFPAY

What this skill does

 

# QFPay Payment API Skill

## Overview

QFPay API is a comprehensive payment solution that offers various payment methods to meet the needs of different businesses. This skill provides complete API integration guidelines including environment configuration, request formats, signature generation, payment types, supported currencies, and status codes.


## Environment Configuration

QFPay API is accessible via three main environments:

| Environment | Base URL | Description |
|-------------|----------|-------------|
| Sandbox | `https://openapi-int.qfapi.com` | For simulating payments without real fund deduction |
| Testing | `https://test-openapi-hk.qfapi.com` | Real payment flow but linked to test accounts (no settlement) |
| Production | `https://openapi-hk.qfapi.com` | Real live payments with actual settlement |

**Important Notes:**
- Transactions in Testing environment using test accounts will NOT be settled
- Always ensure refunds are triggered immediately for test transactions
- Mixing credentials or endpoints across environments will result in signature or authorization errors

### Environment Variables Setup

Configure these environment variables before using the API:

```bash
export QFPAY_APPCODE="your_app_code_here"
export QFPAY_KEY="your_client_key_here"
export QFPAY_MCHID="your_merchant_id"  # Optional, depends on account setup
export QFPAY_ENV="sandbox"  # Options: prod, test, sandbox
```

## API Usage Guidelines

### Rate Limiting

To ensure fair usage and optimal performance:

- **Limit**: Maximum 100 requests per second (RPS) and 400 requests per minute per merchant
- **Exceeding Limit**: API responds with HTTP 429 (Too Many Requests)

### Best Practices

1. **Batch Requests**: Use batch processing to minimize individual requests
2. **Efficient Queries**: Utilize filtering and pagination
3. **Caching**: Implement response caching to avoid repeated requests
4. **Monitoring**: Track API usage and implement logging for request patterns

### Error Handling

When receiving HTTP 429:
1. Pause further requests for a specified duration
2. Implement exponential backoff for retries
3. Log errors for monitoring

### Traffic Spike Management

For anticipated traffic spikes (e.g., promotional events), contact:
- **Technical Support**: [email protected]

## Request Format

### HTTP Request

```
POST /trade/v1/payment
```

### Public Payment Request Parameters

| Attribute | Required | Type | Description |
|-----------|----------|------|-------------|
| `txamt` | Yes | Int(11) | Transaction amount in cents (100 = $1). Suggest > 200 to avoid risk control |
| `txcurrcd` | Yes | String(3) | Transaction currency. See Currencies section for full list |
| `pay_type` | Yes | String(6) | Payment type code. See Payment Types section |
| `out_trade_no` | Yes | String(128) | External transaction number. Must be unique per merchant account |
| `txdtm` | Yes | String(20) | Transaction time format: YYYY-MM-DD hh:mm:ss |
| `auth_code` | Yes (CPM only) | String(128) | Authorization code for scanning barcode/QR. Expires within one day |
| `expired_time` | No (MPM only) | String(3) | QR expiration in minutes. Default: 30, Min: 5, Max: 120 |
| `goods_name` | No | String(64) | Item description. Max 20 chars, UTF-8 for Chinese. Required for App payments |
| `mchid` | No | String(16) | Merchant ID. Required if assigned, must NOT be included if not assigned |
| `udid` | No | String(40) | Unique device ID for internal tracking |
| `notify_url` | No | String(256) | URL for asynchronous payment notifications |

### HTTP Header Requirements

| Field | Required | Description |
|-------|----------|-------------|
| `X-QF-APPCODE` | Yes | App code assigned to merchant |
| `X-QF-SIGN` | Yes | Signature generated per signature algorithm |
| `X-QF-SIGNTYPE` | No | Signature algorithm. Use `SHA256` or defaults to `MD5` |

### Content Specifications

- **Character Encoding**: UTF-8
- **Method**: POST/GET (depends on endpoint)
- **Content-Type**: application/x-www-form-urlencoded

## Response Format

### Success Response Structure

```json
{
  "respcd": "0000",
  "respmsg": "success",
  "data": {
    "txamt": "100",
    "out_trade_no": "20231101000001",
    "txcurrcd": "HKD",
    "txstatus": "SUCCESS",
    "qf_trade_no": "9000020231101000001",
    "pay_type": "800101",
    "txdtm": "2023-11-01 10:00:00"
  }
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `respcd` | String(4) | Return code. "0000" means success |
| `respmsg` | String(64) | Message description of respcd |
| `data` | Object | Payment transaction data |

### Data Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `txamt` | String | Transaction amount in cents |
| `out_trade_no` | String | Merchant's original order number |
| `txcurrcd` | String | Currency code (e.g., HKD) |
| `txstatus` | String | Payment status: SUCCESS, FAILED, PENDING |
| `qf_trade_no` | String | QFPay's unique transaction number |
| `pay_type` | String | Payment method code |
| `txdtm` | String | Payment time (YYYY-MM-DD HH:mm:ss) |

### Signature Verification

Response may include `X-QF-SIGN` and `X-QF-SIGNTYPE` headers. Verify by:
1. Extracting data fields in sorted order
2. Concatenating as key1=value1&key2=value2&...
3. Appending client key
4. Generating MD5 hash and comparing

## Signature Generation

All API requests must include a digital signature in the HTTP header:

```
X-QF-SIGN: <your_signature>
```

### Step-by-Step Guide

#### Step 1: Sort Parameters

Sort all request parameters by parameter name in ASCII ascending order.

**Example:**

| Parameter | Value |
|-----------|-------|
| `mchid` | `ZaMVg12345` |
| `txamt` | `100` |
| `txcurrcd` | `HKD` |

Sorted result:
```
mchid=ZaMVg12345&txamt=100&txcurrcd=HKD
```

#### Step 2: Append Client Key

Append your secret `client_key` to the string.

If `client_key = abcd1234`:
```
mchid=ZaMVg12345&txamt=100&txcurrcd=HKDabcd1234
```

#### Step 3: Hash the String

Hash using MD5 or SHA256 (SHA256 recommended):

```
SHA256("mchid=ZaMVg12345&txamt=100&txcurrcd=HKDabcd1234")
```

#### Step 4: Add to Header

```
X-QF-SIGN: <your_hashed_signature>
```

### Important Notes

- Do NOT insert line breaks, tabs, or extra spaces
- Parameter names and values are case-sensitive
- Double-check parameter order and encoding if signature fails

### Code Examples

#### Python

```python
import os
import hashlib

APPCODE = os.getenv('QFPAY_APPCODE')
KEY = os.getenv('QFPAY_KEY')

def generate_signature(params, key):
    """Generate MD5 signature"""
    keys = list(params.keys())
    keys.sort()
    query = []
    for k in keys:
        if k not in ('sign', 'sign_type') and (params[k] or params[k] == 0):
            query.append(f'{k}={params[k]}')
    
    data = '&'.join(query) + key
    md5 = hashlib.md5()
    md5.update(data.encode('utf-8'))
    return md5.hexdigest().upper()

def generate_signature_sha256(params, key):
    """Generate SHA256 signature"""
    keys = list(params.keys())
    keys.sort()
    query = []
    for k in keys:
        if k not in ('sign', 'sign_type') and (params[k] or params[k] == 0):
            query.append(f'{k}={params[k]}')
    
    data = '&'.join(query) + key
    sha256 = hashlib.sha256()
    sha256.update(data.encode('utf-8'))
    return sha256.hexdigest().upper()
```

## Payment Types

The `pay_type` parameter specifies which payment method to use. This affects transaction routing and UI requirements.

**Note**: Not all `pay_type` values are enabled for every merchant. Contact [email protected] for clarification.

### Supported Payment Types

| Code | Description |
|------|-------------|
| 800008 | CPM for WeChat, Alipay, UnionPay Quick