Subscription Integration Process

Subscription allows merchants to create and publish subscription plans on-chain via the admin console, then generate subscription links for users through the API. After users complete signing and authorization on the subscription page, merchants can initiate periodic charges and synchronize subscription status via callback notifications or query interfaces.

1. Subscription Activation Process

The sequence diagram of the subscription activation process is as follows:

The integration flow is as follows:

1. The admin first creates a subscription plan in the admin console and completes multi-sig approval. The plan only takes effect on-chain after approval passes. The merchant must record the corresponding planId.
2. The merchant system calls /subscribe/payment/create (Create Subscription Link) to initiate a subscription request to Pay Protocol. After validating the request parameters, Pay Protocol returns the subscription ID, the subscription page path paymentUrl, and the link expiration time.
3. The merchant system must append the official domain to paymentUrl before redirecting the user to the subscription page. The user completes wallet connection, signing confirmation, and deduction allowance authorization on that page.
4. When a subscription-related event is triggered, Pay Protocol sends a callback notification via POST to notifyUrl (provided by the merchant when creating the subscription). The merchant must distinguish between signing, authorization, billing, and cancellation events using the subscriptionType field in the callback.
5. The merchant may also call /subscribe/list (Get Subscription List) to query subscription status without relying solely on the frontend redirect result.

warning

• The paymentUrl returned by the API is a relative path. It must be prepended with the Pay Protocol official domain before it can be accessed: https://payment.payprotocol.network for production and https://payment-sandbox.payprotocol.network for sandbox.
• After receiving a callback notification, the merchant system must verify the signature (by validating the X-PAY-SIGN header) to ensure the notification was sent by Pay Protocol. See Callback Signature Verification for details.
• After verifying the signature, make sure to validate the subscription ID, plan ID, and user identifier in the notification, and handle subsequent business logic based on subscriptionType and the status fields.
• A frontend page redirect does not mean the subscription has taken effect. Merchants should treat the SubscriptionApprove callback or the subscription status returned by the query interface as the authoritative result.

2. Periodic Billing Process

After the user completes authorization, the merchant must actively initiate periodic billing. The sequence diagram of the billing process is as follows:

The integration flow is as follows:

1. The merchant system calls /subscribe/chargeable/list (Get Chargeable Subscription List) to retrieve subscriptions that are due for billing. The response includes subscriptionId, userHash, nextPayTime, and other fields that serve as inputs for signing and reconciliation.
2. The merchant submits the chargeable subscription data to the signer interface, which completes signing and automatically broadcasts the transaction. Use the Sign EVM Subscription Billing interface for EVM chains and the Sign TVM Subscription Billing interface for TVM chains.
3. After a successful or failed deduction, Pay Protocol sends a subscriptionType=SubscriptionBilling callback notification. The merchant can use this to update the subscription validity period, service status, or trigger a retry/compensation flow.
4. The merchant may also call /subscribe/list to query the current subscription status, or call /subscribe/chargeable/list again to confirm whether the subscription is still in the chargeable list.

warning

• Periodic billing depends on the Signer service. Merchants must complete the signer deployment in advance. See Signer API Reference for deployment instructions.
• When calling the signer, subscriptionIds and userHashs must be in strict one-to-one correspondence, otherwise signing or billing will fail.
• Only process subscriptions where isChargeableCurrentCycle=0 in the query response; if the field indicates the current cycle is not billable, do not initiate a charge for this period.
• Even after the signer interface returns a result, merchants must treat the SubscriptionBilling callback or the final queried status as the authoritative source for billing records.

3. Unsubscription Process

When a user wishes to cancel a subscription, the merchant can create an unsubscription link to guide the user through revoking their on-chain authorization. The sequence diagram of the unsubscription process is as follows:

The integration flow is as follows:

1. When a user needs to cancel their subscription, the merchant system calls /subscribe/cancel/create (Create Unsubscription Link) to initiate an unsubscription request to Pay Protocol.
2. After validating the request parameters, Pay Protocol returns the unsubscription page path paymentUrl and the link expiration time. The merchant must prepend the official domain to paymentUrl before providing the link to the user.
3. After the user enters the unsubscription page and confirms the authorization cancellation via their wallet, the system sends a SubscriptionCancel callback notification asynchronously.
4. The merchant may also call /subscribe/list to query the subscription status and confirm whether the subscription has entered the authorization-cancelled or terminated state.

warning

• The access rules for unsubscription links are the same as for subscription links: the official domain must be prepended before use; the relative path returned by the API cannot be used directly.
• After receiving a SubscriptionCancel callback, the merchant system must verify the signature before updating the local subscription status and stopping further automatic billing or service provisioning.
• After a user unsubscribes, merchants should confirm the subscription status via the query interface or callback result to avoid initiating charges against users who have already revoked their authorization.