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
