Skip to main content

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 describes how QFPay sends asynchronous notifications related to the subscription system. This includes:
  • Token creation results
  • Subscription state changes
  • Recurring billing results

​
How to Configure Notification URL

To set your webhook endpoint, please email your webhook URL along with your merchant ID and store ID to: technical.support@qfpay.com

​
Token Creation Notification

Triggered after a payment token is created via Element SDK.

​
Notification Fields

FieldDescription
useridQFPay Store ID
notify_typeNotification type. Value: payment_token
eventOne of: NEW, MATCH, CONFLICT
tokenidID of the generated payment token
token_expiry_dateExpiration date of the token
cardcdMasked card number
card_schemeCard scheme (e.g. VISA, MASTERCARD)
respcdResponse code. 0000 = success
respmsgMessage (e.g. “success”)
sysdtmSystem timestamp
customer_idLinked customer ID (if available)
token_reasonReason for tokenisation
token_referenceToken reference in system

​
Example

{
  "respmsg": "success",
  "card_scheme": "ECMC_DEBIT",
  "cardcd": "5200****1096",
  "tokenid": "tk_6a699aae75094caeb066f****988daa32de",
  "respcd": "0000",
  "token_expiry_date": "2024-04-30 00:00:00",
  "sysdtm": "2024-04-29 15:37:17",
  "notify_type": "payment_token",
  "event": "CONFLICT"
}

​
Subscription Status Change

Sent when the status of a subscription changes.

​
Notification Fields

FieldDescription
notify_typeNotification type. Value: subscription
subscription_idSubscription identifier
stateCurrent state (e.g. ACTIVE, COMPLETED, INCOMPLETE)
sysdtmSystem timestamp

​
Example

{
  "state": "COMPLETED",
  "sysdtm": "2024-04-24 15:19:39",
  "notify_type": "subscription",
  "subscription_id": "sub_e51bb914919*****f6b0fe36d"
}

​
Subscription Payment Result

Sent when a billing attempt occurs (either success or failure).

​
Notification Fields

FieldDescription
notify_typeValue: subscription_payment
subscription_idSubscription ID
subscription_order_idFormat: sub_ord_{subscription_id}_{0001}
respcdResponse code. 0000 = success
respmsgResponse message
syssnSystem transaction ID
txdtmTransaction timestamp
txamtTransaction amount
txcurrcdCurrency
customer_idCustomer ID
product_idProduct ID(s), comma-separated if multiple
cardcdMasked card number
card_schemeCard scheme (present if success)
current_iterationBilling iteration number

​
Example

{
  "txcurrcd": "HKD",
  "reason": "AUTHORISED",
  "cardcd": "",
  "subscription_order_id": "sub_ord_a360f06eb*****ad6aff24c3a",
  "product_id": "prod_8c838c17ddb043b9***11f1a85c30",
  "txdtm": "2024-04-24 15:19:37",
  "txamt": "300",
  "card_scheme": "VISA_DEBIT-SSL",
  "syssn": "20240424180500020000015704",
  "respcd": "0000",
  "subscription_id": "sub_e51bb914919***31d800f6b0fe36d",
  "customer_id": "cust_a9c0bcf2717f4***786a10e5f8f2",
  "notify_type": "subscription_payment",
  "current_iteration": "1"
}

​
Retry Logic & Idempotency

Ensure your webhook receiver is idempotent. The same notification may be delivered multiple times if delivery fails.
If your server does not respond with HTTP 200 OK, the notification will be retried. Retries follow an exponential backoff strategy. The maximum retry count may vary based on internal configuration.