Integration Guide for Recurring Payments

This guide covers the subscription-specific part of a recurring payment integration. Create and confirm the customer payment token first, then use it to create a subscription.

Prerequisites

Before creating a recurring payment, complete the following in Saved Payment Methods:

Create a customer and store the customer_id.
Generate a payment token with the Element SDK.
Confirm and store the token_id from the Token Creation Notification.

You also need a QFPay merchant account with recurring payments enabled, API credentials, and an HTTPS web application.

Understanding the billing flow

The saved payment method and the subscription are separate records:

The saved payment method contains the reusable customer_id and token_id.
The subscription defines the billing product, frequency, and lifecycle.

Depending on your business logic, the initial card payment used to create the token can be either a verification charge or the first subscription charge.

Integration steps

Step 1: Create a product

Define the recurring product and billing cycle. POST /product/v1/create

{
  "name": "Premium Plan",
  "type": "recurring",
  "description": "Monthly premium subscription",
  "txamt": 10000,
  "txcurrcd": "HKD",
  "interval": "monthly",
  "interval_count": 1,
  "usage_type": "licensed"
}

Store the returned product_id.

Step 2: Create the subscription

Create the subscription with the saved customer, token, and recurring product. POST /subscription/v1/create

{
  "products": [
    {
      "product_id": "prod_xyz789",
      "quantity": 1
    }
  ],
  "customer_id": "cust_abc123",
  "token_id": "tok_def456",
  "start_time": "2024-01-01 00:00:00"
}

The response returns a subscription_id and its current state.

Step 3: Handle subscription notifications

Implement the Subscription Webhook to receive subscription state changes and recurring billing results.

Token Creation Notifications are documented separately in Saved Payment Methods.

Testing

Test the complete flow in sandbox: create the saved payment method, confirm the token notification, create a product, create the subscription, and verify webhook handling.

Best practices

Validate and process webhooks idempotently.
Store customer_id, token_id, product_id, and subscription_id in your backend.
Handle failed billing and customer notifications according to your retry policy.
Test cancellation, token replacement, and failed-payment paths before production.

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

Integration Guide for Recurring Payments

Prerequisites

Understanding the billing flow

Integration steps

Step 1: Create a product

Step 2: Create the subscription

Step 3: Handle subscription notifications

Testing

Best practices

Next steps

​Prerequisites

​Understanding the billing flow

​Integration steps

​Step 1: Create a product

​Step 2: Create the subscription

​Step 3: Handle subscription notifications

​Testing

​Best practices

​Next steps

Prerequisites

Understanding the billing flow

Integration steps

Step 1: Create a product

Step 2: Create the subscription

Step 3: Handle subscription notifications

Testing

Best practices

Next steps