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:

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:

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: technical.support@qfpay.com

Request Format

HTTP Request

POST /trade/v1/payment

Public Payment Request Parameters

HTTP Header Requirements

Content Specifications

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

Response Format

Success Response Structure

{
  "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

Data Object Fields

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:

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

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 technical.support@qfpay.com for clarification.

Supported Payment Types

Special Remarks

• 801101: Transaction amount must be greater than 1 HKD
• 802001: This payment method does not support refunds

Supported Currencies

All codes follow ISO 4217 format (3-letter uppercase):

Note: Some payment methods may only support HKD. Verify with your integration manager before non-HKD transactions.

Status Codes

Standard respcd values returned by QFPay API:

Usage Examples

Complete Payment Flow (Python)

import os
import requests
import hashlib
import datetime
import time

# Load configuration from environment variables
APPCODE = os.getenv('QFPAY_APPCODE')
KEY = os.getenv('QFPAY_KEY')
MCHID = os.getenv('QFPAY_MCHID')
ENV = os.getenv('QFPAY_ENV', 'test')

# Environment URLs
ENV_URLS = {
    'prod': 'https://openapi-hk.qfapi.com',
    'test': 'https://test-openapi-hk.qfapi.com',
    'sandbox': 'https://openapi-int.qfapi.com'
}

BASE_URL = ENV_URLS.get(ENV, ENV_URLS['test'])

def generate_signature(params, key, sign_type='SHA256'):
    """Generate signature for QFPay API request"""
    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
    
    if sign_type == 'SHA256':
        sha256 = hashlib.sha256()
        sha256.update(data.encode('utf-8'))
        return sha256.hexdigest().upper()
    else:
        md5 = hashlib.md5()
        md5.update(data.encode('utf-8'))
        return md5.hexdigest().upper()

def create_payment(amount, currency, pay_type, goods_name, notify_url=None):
    """Create a payment request"""
    params = {
        'txamt': str(amount),
        'txcurrcd': currency,
        'pay_type': pay_type,
        'out_trade_no': f"ORDER{int(time.time() * 10000)}",
        'txdtm': datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
        'goods_name': goods_name
    }
    
    if MCHID:
        params['mchid'] = MCHID
    
    if notify_url:
        params['notify_url'] = notify_url
    
    signature = generate_signature(params, KEY)
    
    headers = {
        'X-QF-APPCODE': APPCODE,
        'X-QF-SIGN': signature,
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    
    response = requests.post(
        f'{BASE_URL}/trade/v1/payment',
        data=params,
        headers=headers
    )
    
    return response.json()

def query_transaction(out_trade_no):
    """Query transaction status"""
    params = {
        'out_trade_no': out_trade_no,
        'txdtm': datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    }
    
    if MCHID:
        params['mchid'] = MCHID
    
    signature = generate_signature(params, KEY)
    
    headers = {
        'X-QF-APPCODE': APPCODE,
        'X-QF-SIGN': signature,
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    
    response = requests.post(
        f'{BASE_URL}/trade/v1/query',
        data=params,
        headers=headers
    )
    
    return response.json()

def refund_transaction(out_trade_no, txamt, qf_trade_no=None):
    """Process a refund"""
    params = {
        'out_trade_no': out_trade_no,
        'txamt': str(txamt),
        'txdtm': datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    }
    
    if qf_trade_no:
        params['qf_trade_no'] = qf_trade_no
    
    if MCHID:
        params['mchid'] = MCHID
    
    signature = generate_signature(params, KEY)
    
    headers = {
        'X-QF-APPCODE': APPCODE,
        'X-QF-SIGN': signature,
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    
    response = requests.post(
        f'{BASE_URL}/trade/v1/refund',
        data=params,
        headers=headers
    )
    
    return response.json()

# Example usage
if __name__ == '__main__':
    # Create a payment
    result = create_payment(
        amount=100,  # $1.00 HKD
        currency='HKD',
        pay_type='800101',
        goods_name='Test Product'
    )
    print(f"Payment created: {result}")
    
    if result.get('respcd') == '0000':
        out_trade_no = result['data']['out_trade_no']
        
        # Query transaction
        query_result = query_transaction(out_trade_no)
        print(f"Transaction status: {query_result}")

Environment Configuration with Multiple Merchants

import os

# Configuration loader from environment
class QFPayConfig:
    def __init__(self, env='sandbox'):
        self.env = env
        self.appcode = os.getenv(f'QFPAY_{env.upper()}_APPCODE') or os.getenv('QFPAY_APPCODE')
        self.key = os.getenv(f'QFPAY_{env.upper()}_KEY') or os.getenv('QFPAY_KEY')
        self.mchid = os.getenv(f'QFPAY_{env.upper()}_MCHID') or os.getenv('QFPAY_MCHID')
        
    @property
    def base_url(self):
        urls = {
            'prod': 'https://openapi-hk.qfapi.com',
            'test': 'https://test-openapi-hk.qfapi.com',
            'sandbox': 'https://openapi-int.qfapi.com'
        }
        return urls.get(self.env, urls['sandbox'])

# Usage
config = QFPayConfig(env=os.getenv('QFPAY_ENV', 'sandbox'))
print(f"Using base URL: {config.base_url}")

Important Notes

1. Signature Security: Never expose your client_key in frontend code or client-side applications. Always compute signatures on the server side.

2. Order Number Uniqueness: out_trade_no must be unique across all payment and refund requests under the same merchant account.

3. Character Encoding: All requests and responses use UTF-8 encoding.

4. Timeout Handling: For payment requests that don't return promptly, implement a polling mechanism to query transaction status.

5. Async Notifications: Configure notify_url to receive asynchronous payment completion notifications and verify notification signatures.

6. Refund Limitations: FPS (802001) payment type does not support refunds. Confirm business requirements before integration.

7. Amount Format: Amount is in cents. For example, 100 represents 1 HKD.

8. Timezone: The txdtm parameter uses the merchant's local timezone.

9. Environment Variables: Always load sensitive credentials from environment variables, never hardcode them in source files.

Technical Support

For any integration issues, contact:

• Email: technical.support@qfpay.com
• Documentation: https://sdk.qfapi.com
• Postman Collection: https://sdk.qfapi.com/assets/files/qfpay_openapi_payment_request.postman_collection-c8de8c8fe69f3fcd5a7653d41c289a29.json

See Also

• QFPay Developer Center
• Payment Integration Guides
• Checkout Integration