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.
This page documents the available API endpoints for recurring payments. Make sure you have read the Recurring Overview before using these APIs.
1. Create Customer
POST /customer/v1/create
Creates a new customer profile.
Request Parameters
| Parameter | Type | Required | Description |
|---|
name | String | No | Customer name |
phone | String | No | Contact number |
email | String | No | Email address |
billing_address | String (JSON) | No | JSON string of billing address |
Response
Returns the customer_id.
2. Update Customer
POST /customer/v1/update
Updates an existing customer.
Request Parameters
| Parameter | Type | Required | Description |
|---|
customer_id | String | Yes | QFPay system customer ID |
name | String | No | Customer name |
phone | String | No | Contact number |
email | String | No | Email address |
billing_address | JSON | No | JSON object of billing address |
Response
Returns number of affected rows.
3. Query Customers
POST /customer/v1/query
Search for customers.
Request Parameters
| Parameter | Type | Required | Description |
|---|
customer_id | String | No | Customer ID |
name | String | No | Customer name |
phone | String | No | Contact number |
email | String | No | Email address |
page | Int | No | Default = 1 |
page_size | Int | No | Default = 10, max = 100 |
Response
List of matching customers.
4. Delete Customer
POST /customer/v1/delete
Deletes a customer. This action is irreversible.
Request Parameters
| Parameter | Type | Required | Description |
|---|
customer_id | String | Yes | Customer ID to delete |
Response
Returns deleted customer ID and row count.
5. Create Product
POST /product/v1/create
Creates a recurring billing product.
Request Parameters
| Parameter | Type | Required | Description |
|---|
name | String | Yes | Product name |
type | String | Yes | Must be recurring |
description | String | No | Product description |
txamt | Int | Yes | Amount in cents (100 = $1) |
txcurrcd | String | Yes | Currency (e.g. HKD) |
interval | String | Yes | Billing cycle: monthly, yearly, etc. |
interval_count | Int | Yes | Interval count (e.g. 1 month = 1) |
usage_type | String | Yes | Must be licensed |
In the sandbox environment, minutes and hours can be used in the interval field for testing purposes.
Response
Returns generated product_id.
6. Update Product
POST /product/v1/update
Updates product metadata.
Request Parameters
| Parameter | Type | Required | Description |
|---|
product_id | String | Yes | Product ID to update |
name | String | No | New name |
description | String | No | New description |
Response
Returns number of affected rows.
7. Query Products
POST /product/v1/query
Search for products.
Request Parameters
| Parameter | Type | Required | Description |
|---|
product_id | String | No | Product ID |
name | String | No | Product name |
description | String | No | Description |
txcurrcd | String | No | Currency |
interval | String | No | monthly / yearly |
page | Int | No | Default = 1 |
page_size | Int | No | Default = 10, max = 100 |
Response
List of matching products.
8. Delete Product
POST /product/v1/delete
Deletes a product (must not be linked to active subscriptions).
Request Parameters
| Parameter | Type | Required | Description |
|---|
product_id | String | Yes | Product ID to delete |
Response
Returns deleted product ID and row count.
9. Create Subscription
You must create customer_id, product_id, and token_id before calling the subscription API.
/subscription/v1/create
Creates a recurring subscription.
Request Parameters
| Parameter | Type | Required | Description |
|---|
customer_id | String | Yes | Linked customer ID |
token_id | String | Yes | Linked payment token |
products | List | Yes | Product ID and quantity |
total_billing_cycles | Int | No | Total billing periods (null = indefinite) |
start_time | String | No | ISO timestamp to start subscription |
Products Object
| Attribute | Type | Required | Description |
|---|
product_id | String | Yes | Unique product identifier |
quantity | Int | No | Default = 1 |
Example Request
{
"products": [
{
"product_id": "prod_54c3772d******9a54b236e09ec74f",
"quantity": 1
}
],
"customer_id": "cust_aaf6aae94******982c54c9cae5ba32",
"token_id": "tk_a99892fd*********d3417d168a18bb",
"total_billing_cycles": 2,
"start_time": "2020-05-14 12:32:56"
}
Response (data field)
| Attribute | Type | Description |
|---|
subscription_id | String | Unique subscription identifier |
state | String | ACTIVE, INCOMPLETE, COMPLETED |
10. Update Subscription
POST /subscription/v1/update
Request Parameters
| Attribute | Type | Required | Description |
|---|
subscription_id | String | Yes | Unique subscription ID |
total_billing_cycles | Int | No | Null = indefinite |
start_time | String | No | First billing time |
token_id | String | No | Payment token |
products | Object | No | List of product objects |
Response (data field)
| Attribute | Type | Description |
|---|
subscription_id | String | Subscription ID |
rowAffected | Int | Number of records updated |
11. Query Subscription
POST /subscription/v1/query
Request Parameters
| Attribute | Type | Required | Description |
|---|
page | Int | No | Default = 1 |
page_size | Int | No | Default = 10, max = 100 |
subscription_id | String | No | Subscription ID |
customer_id | String | No | Customer ID |
state | String | No | e.g. INCOMPLETE, ACTIVE |
Sample Response
{
"resperr": "success",
"respcd": "0000",
"respmsg": "success",
"data": [
{
"subscription_id": "sub_e120378de*******da066f690da75",
"customer_id": "cust_5ba1539f*******c9bda11d12c854e36",
"token_id": "tk_9ac510017*******69b614e8f7ee",
"state": "ACTIVE",
"total_billing_cycles": 3,
"completed_iteration": 1,
"last_billing_time": "2024-11-21T11:12:06Z",
"next_billing_time": "2024-11-21T11:13:06Z",
"products": [
{ "product_id": "prod_8efecd0bd******b9aa1ec5ec01", "quantity": 1 }
]
}
]
}
12. Cancel Subscription
POST /subscription/v1/cancel
Request Parameters
| Attribute | Type | Required | Description |
|---|
subscription_id | String | Yes | Subscription ID |
13. Query Subscription Orders
POST /subscription/billing_order/v1/list
Request Parameters
| Attribute | Type | Required | Description |
|---|
subscription_id | String | Yes | Subscription ID |
page | Int | No | Default = 1 |
page_size | Int | No | Default = 10, max = 100 |
Response (data field)
| Attribute | Type | Description |
|---|
subscription_order_id | String | Format: sub_ord_{subscription_id}_{0001} |
subscription_id | String | Parent subscription |
trigger_by | String | auto or manual |
sequence_no | Int | Billing iteration number |
14. Manual Charge Subscription
POST /subscription/v1/charge
Request Parameters
| Attribute | Type | Required | Description |
|---|
subscription_id | String | Yes | Subscription ID |
subscription_order_id | String | No | Specific order to retry |
This API is only valid for subscriptions with failed billing and state UNPAID, INCOMPLETE, or PAST_DUE.
- If manual charge occurs before next billing time → subscription remains
ACTIVE
- If manual charge occurs after next billing time → subscription will be cancelled
- If manual charge fails → subscription state remains unchanged
