Subscription API Reference - QFPay Developer Centre

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: `weekly`, `monthly`, `yearly`
`interval_count`	Int	Yes	NO. of interval units (e.g. 1 month = 1) Weekly: weekly + 1 Monthly: monthly + 1 Quarterly: monthly + 3 Semi-annually: monthly + 6 Annually: yearly + 1 (or monthly + 12)
`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.

POST /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

​1. Create Customer

​Request Parameters

​Response

​2. Update Customer

​Request Parameters

​Response

​3. Query Customers

​Request Parameters

​Response

​4. Delete Customer

​Request Parameters

​Response

​5. Create Product

​Request Parameters

​Response

​6. Update Product

​Request Parameters

​Response

​7. Query Products

​Request Parameters

​Response

​8. Delete Product

​Request Parameters

​Response

​9. Create Subscription

​Request Parameters

​Products Object

​Example Request

​Response (data field)

​10. Update Subscription

​Request Parameters

​Response (data field)

​11. Query Subscription

​Request Parameters

​Sample Response

​12. Cancel Subscription

​Request Parameters

​13. Query Subscription Orders

​Request Parameters

​Response (data field)

​14. Manual Charge Subscription

​Request Parameters

1. Create Customer

Request Parameters

Response

2. Update Customer

Request Parameters

Response

3. Query Customers

Request Parameters

Response

4. Delete Customer

Request Parameters

Response

5. Create Product

Request Parameters

Response

6. Update Product

Request Parameters

Response

7. Query Products

Request Parameters

Response

8. Delete Product

Request Parameters

Response

9. Create Subscription

Request Parameters

Products Object

Example Request

Response (data field)

10. Update Subscription

Request Parameters

Response (data field)

11. Query Subscription

Request Parameters

Sample Response

12. Cancel Subscription

Request Parameters

13. Query Subscription Orders

Request Parameters

Response (data field)

14. Manual Charge Subscription

Request Parameters