---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/sessionCreate/index.md
description: >-
  The Create Subscription Checkout Session API creates a subscription plan
  together with a cashier session, and returns the token, JS SDK URL and payment
  link for the frontend to complete the first payment.
---
# Create Subscription Checkout Session

```apidef
endpoint: POST /v4/subscriptions/sessions/create
name: Create Subscription Checkout Session
summary: Create a subscription checkout session
tags: Subscription, Hosted
```

The Create Subscription Checkout Session API creates a subscription plan together with a cashier session, and returns the token, JS SDK URL and payment link for the frontend to complete the first payment.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ merchantSubscriptionId | string | M | Merchant-defined unique subscription plan ID. |
| └─ merchantTransactionId | string | M | Merchant transaction ID for the first payment. Sandbox verified (2026-10-21): required; absence returns `merchantTransactionId:must not be blank` (102000). |
| └─ requestId | string | M | Unique merchant request ID. |
| └─ description | string | M | Subscription description. |
| └─ startAt | string | O | Subscription start time as a 10-digit second-level timestamp string. |
| └─ endAt | string | O | Subscription end time as a 10-digit second-level timestamp string. |
| └─ notifyUrl | string | M | Subscription notification URL.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications. |
| └─ period | object | M | Subscription billing cycle. |
| └─ └─ count | integer | M | Number of units in one formal billing cycle. Must be at least 1 . For example, unit = MONTH and count = 1 means monthly billing. This is not the total number of billing cycles. |
| └─ └─ unit | string | M | Subscription period unit type. Valid values include: YEAR : the subscription cycle is measured in years.; MONTH : the subscription cycle is measured in months.; WEEK : the subscription cycle is measured in weeks.; DAY : the subscription cycle is measured in days.; |
| └─ totalPeriodCount | integer | O | Total number of formal billing cycles in the subscription plan. Must be at least 1 and excludes the trial period. If omitted, the number of formal billing cycles is unlimited. |
| └─ trial | object | O | Trial settings. |
| └─ └─ startAt | string | O | Trial start time as a 10-digit second-level timestamp string. |
| └─ └─ endAt | string | C | Trial end time as a 10-digit second-level timestamp string. At least one of endAt or periodDays is required. If both are provided, endAt takes precedence. |
| └─ └─ periodDays | integer | C | Trial duration in days, calculated from the trial start time startAt . |
| └─ autoRecovery | object | O | Automatic retry settings. |
| └─ └─ enabled | boolean | O | Whether automatic retry is enabled. Automatic retry is enabled by default. true : retry enabled; false : retry disabled; |
| └─ flatPrice | object | M | Recurring amount and currency for each formal billing cycle. The amount must not be zero. |
| └─ └─ amount | string | M | Recurring billing amount. The current implementation does not allow 0 . |
| └─ └─ currency | string | M | Recurring billing currency. |
| └─ discount | object | O | Subscription discount configuration. Applies only to formal billing cycles and not to the trial period. |
| └─ └─ type | string | M | Discount type. Valid values: fixedAmount : fixed-amount discount.; percentage : percentage discount.; |
| └─ └─ amountOff | string | C | Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff . |
| └─ └─ percentOff | string | C | Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff . |
| └─ └─ durationCount | string | M | Number of formal billing cycles for which the discount applies, excluding the trial period. |
| └─ redirectUrl | string | M | Redirect URL after subscription or payment handling. |
| └─ payCancelUrl | string | M | Redirect URL when the shopper cancels payment. |
| └─ payResultUrl | string | M | Payment result page URL that the customer is redirected to after the initial payment completes. |
| └─ paymentNotifyUrl | string | O | Payment result notification URL for this session.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications. |
| └─ remark | string | O | Merchant extension field. |
| └─ language | string | O | Interaction language. |
| └─ tradeCountry | string | M | Country used for the PingPong checkout. |
| └─ shopperIP | string | M | User's IP address for placing the order, supports IPv4 format. |
| └─ merchantSource | string | C | Site-building platform identifier when applicable. |
| └─ merchantRequestBillDescriptor | string | O | Merchant-defined dynamic billing descriptor, up to 22 characters. Only English letters, digits, whitespace, and these ASCII punctuation marks are allowed: , . ( ) - / : . Chinese characters and other special characters are not allowed. Different channels may apply appropriate truncation. |
| └─ customerId | string | M | PingPong customer ID. Create the customer first via the Create Customer: /en/notes/subscription/invoice/customer/create/ API. Sandbox verified (2026-10-21): if omitted, 102000 customerId: must not be blank is returned. |
| └─ paymentMethods | array | O | Allowed payment methods displayed on checkout, used to control which payment methods can be shown to the user for this subscription checkout. Currently supported values: CARD International credit card; ApplePay; GooglePay; Klarna; PayPal; |
| └─ customer | object | O | Customer information. |
| └─ └─ firstName | string | O | Customer first name. |
| └─ └─ lastName | string | O | Customer last name. |
| └─ └─ email | string | O | Customer email. |
| └─ └─ phone | string | O | Customer phone number. |
| └─ └─ phoneCountryCode | string | O | Phone country code. |
| └─ └─ identificationType | string | O | Identification type. |
| └─ └─ identificationId | string | O | Identification number. |
| └─ └─ birthDate | string | O | Birth date. |
| └─ └─ accountNumber | string | O | Account number. |
| └─ └─ domesticCardNumber | string | O | Domestic card number. |
| └─ └─ domesticCardIssuingDate | string | O | Domestic card issuing date. |
| └─ └─ domesticCardExpireMonth | string | O | Domestic card expiry month. |
| └─ └─ domesticCardExpireYear | string | O | Domestic card expiry year. |
| └─ goods | object | M | Goods information. |
| └─ └─ name | string | M | Product name. |
| └─ └─ description | string | O | Product description. |
| └─ └─ sku | string | O | Product number, product SKU. |
| └─ └─ unitPrice | string | M | Unit price of the product. Note: the sum of unitPrice × number must equal flatPrice.amount , otherwise 301012 is returned. |
| └─ └─ unitTaxAmount | string | C | Tax per item, mandatory when the total order amount includes tax. |
| └─ └─ taxRate | string | O | Tax rate. |
| └─ └─ totalDiscountAmount | string | C | Total discount amount per item, mandatory when the total order amount involves discounts. |
| └─ └─ number | string | M | Quantity of the product purchased. |
| └─ └─ imgUrl | string | M | Main image link of the product. |
| └─ └─ virtualProduct | string | O | Whether it is a virtual product, virtual goods ( Y / N ). |
| └─ └─ itemType | string | O | Product type, enumerated values: 1 / 2 / 3 , corresponding meanings are as follows: 1 DIGITAL: Digital products; 2 PHYSICAL: Physical products; 3 SERVICE: Services; |
| └─ billingAddress | object | M | Billing address. |
| └─ └─ street | string | M | Billing street. |
| └─ └─ postcode | string | M | Postal code. |
| └─ └─ city | string | M | City. |
| └─ └─ state | string | M | State or province. |
| └─ └─ country | string | M | Two-letter country code. |
| └─ └─ district | string | O | District. |
| └─ browserInfo | object | O | Browser information. Required for card payments. |
| └─ └─ windowSize | string | O | Window size: 01 -250x400; 02 -390x400; 03 -500x600; 04 -600x400; 05 -Full screen; |
| └─ └─ acceptHeader | string | O | HTTP response header information, example value: text/html, application/xhtml+xml, application/xml; q=0.9, image/webp, image/apng, *; q=0.8 |
| └─ └─ colorDepth | string | O | Window color, obtained from browser screen.colorDepth. Example value: 32 |
| └─ └─ screenHeight | string | O | Window height. |
| └─ └─ screenWidth | string | O | Screen width (unit: pixels). |
| └─ └─ jetLag | string | O | Time difference in minutes between UTC and the cardholder's browser local time. |
| └─ └─ userAgent | string | O | Browser user agent information. |
| └─ └─ javaEnabled | boolean | O | Whether the cardholder's device can execute Java. |
| └─ └─ javaScriptEnabled | boolean | O | Indicates whether the shopper's browser can execute JavaScript. If the field is absent, it is assumed to have the default value of true . |
| └─ device | object | M | Device information. accessModel values can be omitted. |
| └─ └─ orderTerminal | string | M | 01 - Mobile browser (app); 02 - PC browser (pc); 04 - SDK (ios); 05 - SDK (Android); 06 - WeChat Mini Program; 09 - QR Code; |

### Request Example

```json
{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_M_202606110002\",\"merchantTransactionId\":\"MT_SUB_202606110002\",\"requestId\":\"REQ_SUB_SESSION_001\",\"description\":\"Monthly membership subscription\",\"startAt\":\"1781116800\",\"notifyUrl\":\"https://merchant.example.com/notify/subscription\",\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"trial\":{\"startAt\":\"1781116800\",\"endAt\":\"1781721600\",\"periodDays\":7},\"autoRecovery\":{\"enabled\":true},\"flatPrice\":{\"amount\":\"9.99\",\"currency\":\"USD\"},\"discount\":{\"type\":\"percentage\",\"percentOff\":\"10\",\"durationCount\":\"3\"},\"redirectUrl\":\"https://merchant.example.com/subscription/return\",\"payCancelUrl\":\"https://merchant.example.com/subscription/cancel\",\"payResultUrl\":\"https://merchant.example.com/subscription/result\",\"paymentNotifyUrl\":\"https://merchant.example.com/notify/payment\",\"remark\":\"test subscription session\",\"language\":\"en\",\"tradeCountry\":\"US\",\"shopperIP\":\"8.8.8.8\",\"merchantSource\":\"SHOPIFY\",\"merchantRequestBillDescriptor\":\"TEST SUB\",\"customerId\":\"CUS-260507100000000001\",\"paymentMethods\":[\"CARD\"],\"customer\":{\"firstName\":\"John\",\"lastName\":\"Smith\",\"email\":\"john.smith@example.com\",\"phone\":\"13800138000\",\"phoneCountryCode\":\"86\"},\"goods\":{\"name\":\"Membership\",\"description\":\"Monthly membership\",\"sku\":\"SKU_SUB_001\",\"unitPrice\":\"9.99\",\"number\":\"1\",\"imgUrl\":\"https://merchant.example.com/goods/sub.png\",\"virtualProduct\":\"Y\",\"itemType\":\"1\"},\"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\"}}"
}
```

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ requestId | string | Merchant request ID. |
| └─ subscriptionId | string | PingPong subscription ID. |
| └─ status | string | Subscription plan status. Valid values include: PENDING : the subscription has been created but is not yet active.; IN_TRIAL : the subscription is in the trial period and service is available, but the first formal charge has not completed yet.; ACTIVE : the subscription is currently active and the user is entitled to the service.; PAST_DUE : the subscription reached its charge time but the current charge failed, entering the dunning or retry stage.; CANCELLED : the subscription has ended and will not renew automatically.; |
| └─ redirectUrl | string | Redirect URL after checkout payment is completed. |
| └─ startAt | string | Subscription start time as a 10-digit second-level timestamp string. |
| └─ endAt | string | Subscription end time as a 10-digit second-level timestamp string. |
| └─ notifyUrl | string | Subscription notification URL. |
| └─ period | object | Subscription billing cycle. |
| └─ └─ count | integer | Number of units in one formal billing cycle. Must be at least 1 . For example, unit = MONTH and count = 1 means monthly billing. This is not the total number of billing cycles. |
| └─ └─ unit | string | Subscription period unit type. Valid values include: YEAR : the subscription cycle is measured in years.; MONTH : the subscription cycle is measured in months.; WEEK : the subscription cycle is measured in weeks.; DAY : the subscription cycle is measured in days.; |
| └─ totalPeriodCount | integer | Total number of formal billing cycles in the subscription plan. Must be at least 1 and excludes the trial period. If omitted, the number of formal billing cycles is unlimited. |
| └─ trial | object | Trial settings. |
| └─ └─ startAt | string | Trial start time as a 10-digit second-level timestamp string. |
| └─ └─ endAt | string | Trial end time as a 10-digit second-level timestamp string. |
| └─ └─ periodDays | integer | Trial duration in days. |
| └─ autoRecovery | object | Automatic retry settings. |
| └─ └─ enabled | boolean | Whether automatic retry is enabled. Automatic retry is enabled by default. true : retry enabled; false : retry disabled; |
| └─ flatPrice | object | Recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | Subscription payment amount. |
| └─ └─ currency | string | Subscription billing currency. |
| └─ discount | object | Current effective subscription discount configuration. Not returned when no discount is configured. |
| └─ └─ type | string | Discount type. Valid values: fixedAmount : fixed-amount discount.; percentage : percentage discount.; |
| └─ └─ amountOff | string | Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff . |
| └─ └─ percentOff | string | Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff . |
| └─ └─ durationCount | string | Number of formal billing cycles for which the discount applies, excluding the trial period. |
| └─ token | string | Subscription checkout session token. |
| └─ innerJsUrl | string | JS SDK URL. |
| └─ paymentUrl | string | Hosted payment URL. |
| └─ partnerTransactionId | string | First payment transaction ID, corresponding to merchantTransactionId in the request. |
| └─ action | object | Follow-up action required from the buyer, containing jsSdkUrl / paymentRedirectUrl etc.; an empty object when no further action is needed. |
| └─ resultCode | string | Acceptance result code; 000000 indicates success. |
| └─ resultMessage | string | Acceptance result description. |

### Response Example

```json
{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_MER_SESSION_001\",\"requestId\":\"REQ_SUB_SESSION_001\",\"subscriptionId\":\"SUB-abcdef1234567890\",\"redirectUrl\":\"https://merchant.example.com/checkout/result\",\"startAt\":\"1785152760\",\"endAt\":\"1817293560\",\"notifyUrl\":\"https://merchant.example.com/subscription/notify\",\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"trial\":{\"startAt\":\"1785152760\",\"endAt\":\"1785757560\",\"periodDays\":7},\"autoRecovery\":{\"enabled\":true},\"status\":\"PENDING\",\"flatPrice\":{\"amount\":\"9.99\",\"currency\":\"USD\"},\"discount\":{\"type\":\"percentage\",\"percentOff\":\"10\",\"durationCount\":\"3\"},\"token\":\"EU:session_token_example\",\"innerJsUrl\":\"https://pay-cdn.pingpongx.com/pp-checkout.js?token=EU:session_token_example\",\"paymentUrl\":\"https://dev-safepay.pingpongx.com?token=EU:session_token_example\",\"partnerTransactionId\":\"MT_SUB_202606110002\",\"action\":{\"jsSdkUrl\":\"https://pay-cdn.pingpongx.com/pp-checkout.js?token=EU:session_token_example\",\"paymentRedirectUrl\":\"https://dev-safepay.pingpongx.com?token=EU:session_token_example\"},\"resultCode\":\"000000\",\"resultMessage\":\"success\"}",
  "code": "000000",
  "description": "SUCCESS"
}
```