Integration Guide
This page is the main integration flow for Subscription. For applicable scenarios of Subscription and the comparison with Recurring(Open in new window) and CodeGrant(Open in new window), see the Subscription Overview. Once you have decided to use Subscription, follow the steps on this page.
Applicable Payment Methods
- Checkout: create a subscription plan and cashier session via Create Subscription Checkout Session; currently displayable payment methods include
VISA,Mastercard,ApplePay,GooglePay,KlarnaandPayPal. API Only: create the subscription directly and submit the first payment via Create Subscription (API Only); currently supportsVISA,Mastercardplus the supportedApplePay,GooglePay,KlarnaandPayPal.
For the trade-offs between the two modes, see Recommended Integration Mode below.
Payment Flow
Flow notes:
- The merchant frontend should first present the subscription price, billing cycle, trial, subscription terms and cancellation entry to the buyer, and have the buyer confirm the subscription.
- The merchant server creates the subscription according to the integration mode: in Checkout mode, create a subscription checkout session first, then the buyer completes the first payment or authorization on the PingPong checkout; in
API Onlymode, the buyer enters or selects the payment method on the merchant's own page, the merchant server creates the subscription with the payment elements, and continues with 3DS, wallet authorization or local payment redirects per the API response. - After the buyer completes the first payment or authorization, the merchant should handle both the subscription-level result and the payment-level result — subscription status changes center on the Subscription Notification.
- After the first period takes effect, PingPong automatically maintains subsequent billing cycles, the trial and automatic retries per the subscription configuration.
- When a renewal fails and automatic retry is enabled, the subscription enters
PAST_DUE; whether to keep providing service is then a merchant-side business decision.
Recommended Integration Mode
If you have decided to use Subscription, choose between Checkout and API Only:
| Mode | Best for | First payment experience | What the merchant handles | Recommendation |
|---|---|---|---|---|
| Checkout | Teams that want to go live faster with PingPong hosting the first payment flow | Cards, wallets, 3DS, embedded and redirect supported | Frontend opens the checkout; server handles notifications and subscription status | Recommended first |
API Only | Teams with an existing self-built payment page, needing full control of the payment experience or already holding the corresponding compliance capabilities | Customizable on the merchant side; 3DS or wallet authorization may still be required | Submit payment elements, handle risk control and follow-up actions, handle notifications | For advanced teams |
Typical cases for preferring Checkout:
- First time launching a subscription capability, minimizing payment-flow integration complexity.
- Need to support
VISA/Mastercardcards, wallets and multiple checkout payment methods at the same time. - Do not want to handle the first payment page, 3DS pages or wallet redirect details yourself.
Typical cases for preferring API Only:
- Mature self-built payment page and server-side payment orchestration already in place.
- Need full control over payment interaction, form structure and payment initiation.
- Already have the corresponding card-payment compliance and risk-control integration capabilities.
API List
Subscription integration typically involves the following APIs and notifications:
| Phase | Type | Document | Required | Purpose |
|---|---|---|---|---|
| Creation & first payment | API | Create Customer | Required | A customer must be created before creating a subscription to obtain the customerId |
| API | Create Subscription Checkout Session | Per integration mode | Creates a subscription checkout session and returns the payment link, token and other data the frontend needs | |
| API | Create Subscription (API Only) | Per integration mode | Creates a subscription via API Only and submits the first payment elements synchronously | |
| Notification | Subscription Notification | Required | Receives subscription status changes, trial conversions, renewal results and plan update results | |
| Guide | General async notification guide | Must-read | General rules for notification address configuration, signature verification, idempotency, ACK, retries and whitelisting | |
| Notification | Payment Notification | Recommended | Gets the payment-level result and payment method details of the first payment or each renewal (includes invoiceId) | |
| API | Query Subscription | Recommended | Pulls the latest subscription snapshot when notifications are delayed, for compensation or status verification | |
| Lifecycle management & reconciliation | API | Query Subscription Payments | Recommended | Queries the payment order of each period and related refund information |
| API | Invoice Details | Recommended | Queries invoice amount, status and customer information by invoiceId (for reconciliation) | |
| API | Invoice Download | Recommended | Gets the invoice PDF download link (valid for 30 days) | |
| API | Receipt Details | Recommended | Queries the payment receipt (including refund records) by receiptId | |
| API | Receipt Download | Recommended | Gets the receipt PDF download link | |
| API | Preview Subscription Update | On demand | Estimates surcharges, refunds and the effective mode before a formal update | |
| API | Update Subscription | On demand | Updates amount, cycle, goods information and billing strategy | |
| API | Cancel Subscription | On demand | Cancels the subscription immediately or at the end of the current billing period |
Integration Preparation
Before integrating Subscription, complete the general preparations in Preparation.
In addition, confirm the following:
- A customer profile has been created for each user: obtain the
customerIdvia the Create Customer API (required when creating a subscription; a missing value returnscustomerId: must not be blank). - Integration mode decided: Checkout or
API Only. - A stable, globally unique
merchantSubscriptionIdfor each subscription plan, and a uniquerequestIdfor each API request. - A publicly reachable subscription notification address
notifyUrl. If you also need payment-level asynchronous results, prepare the payment notification address as well. - Clear subscription business rules: per-period amount, currency, cycle unit, cycle count, first charge method, trial, automatic retry policy, when to suspend service, and cancellation rules.
- Local mappings prepared on the merchant side, at least:
merchantSubscriptionId,subscriptionId, user ID, goods/plan, subscription status, current period and notification handling state. - The subscription price, charge currency, charge frequency, subscription terms, trial period, renewal-failure handling and how to cancel are clearly presented in the user agreement, subscription confirmation page or order confirmation step.
- A clear user-facing cancellation entry, with authorization evidence retained on the merchant side.
- A plan for charge reminders, trial-conversion reminders, invoice / receipt delivery and user entitlement management. These user-touch and entitlement tasks are the merchant's responsibility; PingPong is responsible for subscription execution, notifications and payment records.
Integration Steps
Complete the integration in the following steps:
- Step 0: Create a customer (prerequisite, obtains the
customerId) - Step 1: Create a subscription
- Step 2: Guide the buyer through the first authorization and payment
- Step 3: Get the subscription result and payment result
- Step 4: Manage renewals, recovery charges and plan changes
Step 0: Create a customer (prerequisite)
A customer profile must be created before creating a subscription to obtain the customerId:
// POST /v4/customers/create
{
"requestId": "REQ_CUST_001",
"partnerCustomerId": "user_merchant_001",
"firstName": "Emily",
"lastName": "Johnson",
"email": "emily.johnson@example.com",
"language": "en"
}The response returns a customerId (e.g. CUS-260507100000000001). Store the partnerCustomerId ↔ customerId mapping for later subscription creation.
Step 1: Create a subscription
The merchant should first choose Checkout or API Only per the Recommended Integration Mode; the request must include customerId.
Key fields to focus on when creating a subscription:
| Field | Required | Description |
|---|---|---|
merchantSubscriptionId | M | Merchant-defined unique subscription plan ID; keep using it for later query, update and cancel |
requestId | M | Unique ID of this request |
description | M | Subscription plan description; keep it consistent with the merchant's goods or plan name |
customerId | M | PingPong customer ID (from Create Customer); links the subscription to the customer profile |
notifyUrl | M | Subscription notification address for status changes and plan update results |
payResultUrl | M | Merchant payment result page to redirect back to after the first payment |
flatPrice.amount / flatPrice.currency | M | Actual charge amount and currency of each formal billing period |
period.unit / period.count | M | Unit and unit count of one formal billing cycle, e.g. MONTH + 1 means billing once per month |
tradeCountry | M | Checkout or transaction country, ISO 3166-1 alpha-2 code; required for both Checkout and API Only |
shopperIP | M | The user's IP address when initiating the subscription |
goods | M | The goods or service information of this subscription — a single object, not an array; goods.unitPrice × goods.number must equal flatPrice.amount, otherwise 301012 is returned |
billingAddress | M | Billing address; its state field is required |
device.orderTerminal | M | The terminal type from which the user initiates the subscription |
jsGeneratedData | C | Required for API Only card payments; may be an empty string when unavailable |
totalPeriodCount | O | Total number of formal billing periods, excluding the trial; unlimited when omitted |
startAt | O | Subscription start time; defaults to the current time when omitted |
endAt | O | Subscription plan end time; keep this input — when neither end time nor total period count is specified, renewal continues automatically |
trial | O | Trial configuration; contains only startAt, endAt, periodDays — no amount or currency |
autoRecovery.enabled | O | Whether automatic retry is enabled after a renewal failure |
language | O | Interaction language |
When creating a subscription, keep all time fields on the same main timeline:
| Time field / node | Product rule |
|---|---|
startAt | The effective time of the whole subscription plan and the main anchor for formal period calculation |
trial.startAt | Defaults to startAt when omitted; when provided, it should equal startAt |
trial.endAt | Trial end time; when a trial exists, it is also the start of the first formal billing period and the first formal charge time |
| First formal charge without a trial | Executed at startAt; if startAt is later than the creation time, payment-method binding or authorization is completed after creation and the formal charge happens at startAt |
endAt | No new period charge task is generated after this time; without an end time and total period count, renewal continues automatically per the subscription cycle |
period.count is how many units one billing cycle contains, and totalPeriodCount is how many periods are billed in total. For example, period={"unit":"MONTH","count":1} with totalPeriodCount=12 means 12 monthly formal billing periods; the trial does not count towards these 12 periods. The example below uses a total period count without specifying endAt.
Mode differences:
- Checkout controls which payment methods can be shown to the buyer via
paymentMethods. API Onlysubmits the payment method and payment elements of this first payment viapaymentMethod.- If you also need payment-level asynchronous notifications, both creation APIs use
paymentNotifyUrl.
Checkout session creation example (showing bizContent only):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"merchantTransactionId": "MT_SUB_202607150001",
"requestId": "REQ_SUB_SESSION_202607150001",
"description": "Premium monthly membership",
"notifyUrl": "https://merchant.example.com/notify/subscription",
"paymentNotifyUrl": "https://merchant.example.com/notify/payment",
"redirectUrl": "https://merchant.example.com/subscription/result",
"payCancelUrl": "https://merchant.example.com/subscription/cancel",
"payResultUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"language": "en",
"tradeCountry": "US",
"shopperIP": "8.8.8.8",
"customerId": "CUS-260507100000000001",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"trial": {
"periodDays": 7
},
"autoRecovery": {
"enabled": true
},
"paymentMethods": [
"VISA",
"Mastercard"
],
"goods": {
"name": "Premium membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "9.99",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"billingAddress": {
"street": "1 Market St",
"postcode": "94105",
"city": "San Francisco",
"state": "CA",
"country": "US"
},
"browserInfo": {
"windowSize": "05",
"acceptHeader": "text/html,application/xhtml+xml",
"colorDepth": "32",
"screenHeight": "1080",
"screenWidth": "1920",
"jetLag": "480",
"userAgent": "Mozilla/5.0",
"javaEnabled": false,
"javaScriptEnabled": true
},
"device": {
"orderTerminal": "02"
}
}API Only creation example (showing bizContent only):
{
"merchantSubscriptionId": "SUB_PLAN_202607150002",
"requestId": "REQ_SUB_DIRECT_202607150001",
"description": "Premium monthly membership",
"notifyUrl": "https://merchant.example.com/notify/subscription",
"paymentNotifyUrl": "https://merchant.example.com/notify/payment",
"redirectUrl": "https://merchant.example.com/subscription/result",
"payResultUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"language": "en",
"tradeCountry": "US",
"shopperIP": "8.8.8.8",
"customerId": "CUS-260507100000000001",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"autoRecovery": {
"enabled": true
},
"paymentMethod": {
"type": "scheme",
"cardInfo": {
"number": "4111111111111111",
"expireMonth": "12",
"expireYear": "2030",
"holderFirstName": "John",
"holderLastName": "Smith",
"cvv": "123"
}
},
"jsGeneratedData": "",
"goods": {
"name": "Premium membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "9.99",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"billingAddress": {
"street": "1 Market St",
"postcode": "94105",
"city": "San Francisco",
"state": "CA",
"country": "US"
},
"browserInfo": {
"windowSize": "05",
"acceptHeader": "text/html,application/xhtml+xml",
"colorDepth": "32",
"screenHeight": "1080",
"screenWidth": "1920",
"jetLag": "480",
"userAgent": "Mozilla/5.0",
"javaEnabled": false,
"javaScriptEnabled": true
},
"device": {
"orderTerminal": "02"
}
}Note
- A successful synchronous creation response does not mean the subscription has formally taken effect.
- The first payment result and subscription status changes must be confirmed via server-side notifications or active queries.
- If the first payment depends on a 3DS challenge, wallet authorization or redirect flow, the subscription can only enter
IN_TRIALorACTIVEafter those follow-up actions complete. - Before re-creating the same business subscription for the same user, check on the merchant side whether the
merchantSubscriptionIdalready exists, to avoid duplicate subscriptions. - If the create API times out, returns a gateway error or has an uncertain result, do not immediately rebuild with a new
merchantSubscriptionId. Query the subscription with the original merchant subscription ID first, confirm whether it was already created, then decide whether to retry.
Step 2: Guide the buyer through the first authorization and payment
After creating the subscription, continue the first payment per the integration mode:
- Checkout: use the returned
paymentUrl,innerJsUrlortokento open the subscription checkout on the frontend; the buyer completes the first payment or authorization on the PingPong page. API Only: if the synchronous response returns anaction, a redirect address or other follow-up action, guide the buyer through the 3DS challenge or wallet authorization binding.
Handling recommendations:
- Do not activate service merely because a frontend redirect completed.
redirectUrlis only where the buyer is redirected after completing the payment flow — it does not mean the subscription has taken effect.- If the buyer quits midway, fails a challenge or the payment fails, the subscription may stay
PENDINGor the first payment may have failed — do not grant subscription entitlements prematurely.
Step 3: Get the subscription result and payment result
Subscription scenarios require consuming three kinds of results, each answering a different question:
| Result | Question it answers | Subscription channel | Suggested idempotency key |
|---|---|---|---|
| Subscription result | Whether the subscription is currently effective and can keep receiving service | Subscription Notification | subscriptionId + notifyType + updateAt |
| Payment result | Whether the first or a given period's charge succeeded and how much was charged | Payment Notification | transactionId |
| Refund result | Whether a refund triggered by Update or Cancel completed | Refund Notification | merchantRefundId |
Service activation follows the subscription result; the payment result is for reconciliation, and the refund result is for fund confirmation.
Recommended integration order:
- The Subscription Notification is required — complete address configuration, signature verification, idempotency and ACK per the General async notification guide(Open in new window).
- It is recommended to also receive the Payment Notification; receive the Refund Notification when refunds are involved.
- When notifications are delayed, lost or need compensation, use Query Subscription for subscription status and Query Subscription Payments for per-period payment results.
For the meaning of each notification field (notifyType, status, currentPeriod, merchantTransactionId, etc.), see the corresponding notification reference pages.
Step 4: Manage renewals, recovery charges and plan changes
After the first period takes effect, PingPong automatically drives subsequent renewals, trial conversions and plan changes per the subscription plan. On the merchant side, always handle two separate lines:
| Layer | Question to answer | Fields to watch | How to get it |
|---|---|---|---|
| Subscription level | Can this subscription keep receiving service right now | notifyType, status, currentPeriod, cancelReason | Subscription Notification + Query Subscription |
| Payment level | Was this period actually charged, and did a surcharge or refund happen | paymentRecords, merchantTransactionId, transactionId, amount, currency, status | Payment Notification + Query Subscription Payments |
1. Handle renewals and recovery charges
At the end of each billing period, PingPong automatically initiates the renewal charge per the subscription plan. When a renewal fails with autoRecovery.enabled=true, the subscription may enter PAST_DUE; the merchant should decide whether to keep providing service based on the subscription status, payment records and its own grace-period policy.
For more on renewal failure, automatic retries, recovery charges and query recommendations, see Renewal & Auto-Recovery.
2. Query the subscription plan and payment records
- Use Query Subscription for the latest subscription status, current period, trial, automatic retry configuration and summary records.
- Use Query Subscription Payments for the payment order of each period, related refunds and payment method information.
To judge whether the user keeps their subscription entitlements, look at the subscription status first; to confirm the fund result of a given period, look at payment records and notifications first.
3. Preview and execute plan changes
To upgrade/downgrade a plan, change the amount, adjust the cycle or modify goods information, it is recommended to call Preview Subscription Update first to estimate the surcharge or refund, then call Update Subscription to formally submit the change.
For subscriptions created via checkout, if the surcharge produced by a change requires the buyer to complete a payment, the Update response returns the cashier address in action.paymentRedirectUrl; the merchant should redirect the buyer to that address to complete the payment. See Update & Cancel Rules · Cashier-created subscriptions: redirect to complete the surcharge.
Plan changes involve combinations of effectiveMode, billingAction and prorationMode; different combinations affect the effective time, billing anchor, surcharges and refunds. For detailed rules, see Update & Cancel Rules.
4. The relationship between Update and Cancel
If the subscription plan has an unfinished or completed Update, whether Cancel is allowed depends on the Update state and the new cycle's start time. Even with cancelAtPeriodEnd=true (period-end cancellation), the Update gate cannot be bypassed.
For the complete gates, immediate vs period-end cancellation, and the prorationMode relationship between Update and Cancel, see Update & Cancel Rules.
5. Invoice reconciliation
After each successful charge, PingPong generates an invoice and a payment receipt:
- Getting the invoiceId: the payment notification (
paymentNotifyUrl) payload carries theinvoiceIdfield; - Invoice query: use Invoice Details to query amount, status and customer information by
invoiceId; - Invoice download: use Invoice Download to get the PDF download link (valid for 30 days);
- Receipt query: use Receipt Details by
receiptId(obtained from the Receipt Created Notification); - Receipt download: use Receipt Download to get the PDF download link.
For the complete reconciliation guide and document rhythm, see Invoice Reconciliation.
Next Steps
After completing the main integration flow, return to the Subscription Overview for the full reading guide of each topic (Subscription Status & Notifications, Renewal & Auto-Recovery, Update & Cancel Rules, Scenarios & Best Practices).
Integration Checklist
Before going live, confirm:
merchantSubscriptionId,subscriptionId,customerId, subscription status, current period, amount/currency and the latest event information are persisted.- Subscription, payment and refund notifications are handled separately, with idempotency along each dimension.
- Compensation query logic for delayed or lost notifications is in place.
- User entitlement handling rules for
PAST_DUE, failed trial conversion, period-end cancellation and immediate cancellation are defined. - The subscription cycle, renewal amount, trial rules, cancellation entry and necessary charge reminders are presented to users.
