Create Subscription Checkout Session

About 117 wordsLess than 1 minute

View as Markdown

2026-10-21

POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

periodObjectRequired
Subscription billing cycle.
- countIntegerRequired
  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.
- unitStringRequired
  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.
trialObjectOptional
Trial settings.
- startAtString(10)Optional
  Trial start time as a 10-digit second-level timestamp string.
- endAtString(10)Conditional
  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.
- periodDaysIntegerConditional
  Trial duration in days, calculated from the trial start time startAt.
autoRecoveryObjectOptional
Automatic retry settings.
- enabledBooleanOptional
  Whether automatic retry is enabled. Automatic retry is enabled by default.
  true: retry enabled
  false: retry disabled
flatPriceObjectRequired
Recurring amount and currency for each formal billing cycle. The amount must not be zero.
- amountString(12)Required
  Recurring billing amount. The current implementation does not allow 0.
- currencyString(3)Required
  Recurring billing currency.
discountObjectOptional
Subscription discount configuration. Applies only to formal billing cycles and not to the trial period.
- typeString(32)Required
  Discount type. Valid values:
  fixedAmount: fixed-amount discount.
  percentage: percentage discount.
- amountOffString(12)Conditional
  Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff.
- percentOffString(12)Conditional
  Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff.
- durationCountString(12)Required
  Number of formal billing cycles for which the discount applies, excluding the trial period.
customerObjectOptional
Customer information.
- firstNameStringOptional
  Customer first name.
- lastNameStringOptional
  Customer last name.
- emailString(128)Optional
  Customer email.
- phoneString(20)Optional
  Customer phone number.
- phoneCountryCodeString(5)Optional
  Phone country code.
- identificationTypeString(20)Optional
  Identification type.
- identificationIdString(20)Optional
  Identification number.
- birthDateString(10)Optional
  Birth date.
- accountNumberStringOptional
  Account number.
- domesticCardNumberStringOptional
  Domestic card number.
- domesticCardIssuingDateStringOptional
  Domestic card issuing date.
- domesticCardExpireMonthStringOptional
  Domestic card expiry month.
- domesticCardExpireYearStringOptional
  Domestic card expiry year.
goodsObjectRequired
Goods information.
- nameString(128)Required
  Product name.
- descriptionString(255)Optional
  Product description.
- skuString(255)Optional
  Product number, product SKU.
- unitPriceString(12)Required
  Unit price of the product. Note: the sum of unitPrice × number must equal flatPrice.amount, otherwise 301012 is returned.
- unitTaxAmountString(12)Conditional
  Tax per item, mandatory when the total order amount includes tax.
- taxRateStringOptional
  Tax rate.
- totalDiscountAmountStringConditional
  Total discount amount per item, mandatory when the total order amount involves discounts.
- numberString(12)Required
  Quantity of the product purchased.
- imgUrlString(255)Required
  Main image link of the product.
- virtualProductString(1)Optional
  Whether it is a virtual product, virtual goods (Y/N).
- itemTypeString(1)Optional
  Product type, enumerated values: 1/2/3, corresponding meanings are as follows:
  1 DIGITAL: Digital products
  2 PHYSICAL: Physical products
  3 SERVICE: Services
billingAddressObjectRequired
Billing address.
- streetString(256)Required
  Billing street.
- postcodeString(16)Required
  Postal code.
- cityString(50)Required
  City.
- stateString(128)Required
  State or province.
- countryString(64)Required
  Two-letter country code.
- districtStringOptional
  District.
browserInfoObjectOptional
Browser information. Required for card payments.
- windowSizeStringOptional
  Window size:
  01-250x400
  02-390x400
  03-500x600
  04-600x400
  05-Full screen
- acceptHeaderStringOptional
  HTTP response header information, example value: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/apng, *;q=0.8
- colorDepthStringOptional
  Window color, obtained from browser screen.colorDepth. Example value: 32
- screenHeightStringOptional
  Window height.
- screenWidthStringOptional
  Screen width (unit: pixels).
- jetLagStringOptional
  Time difference in minutes between UTC and the cardholder's browser local time.
- userAgentStringOptional
  Browser user agent information.
- javaEnabledBooleanOptional
  Whether the cardholder's device can execute Java.
- javaScriptEnabledBooleanOptional
  Indicates whether the shopper's browser can execute JavaScript. If the field is absent, it is assumed to have the default value of true.
deviceObjectRequired
Device information. accessModel values can be omitted.
- orderTerminalString(2)Required
  01 - Mobile browser (app)
  02 - PC browser (pc)
  04 - SDK (ios)
  05 - SDK (Android)
  06 - WeChat Mini Program
  09 - QR Code
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
merchantTransactionIdString(64)Required
Merchant transaction ID for the first payment. Sandbox verified (2026-10-21): required; absence returns `merchantTransactionId:must not be blank` (102000).
requestIdString(64)Required
Unique merchant request ID.
descriptionString(256)Required
Subscription description.
startAtString(10)Optional
Subscription start time as a 10-digit second-level timestamp string.
endAtString(10)Optional
Subscription end time as a 10-digit second-level timestamp string.
notifyUrlString(512)Required
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.
totalPeriodCountIntegerOptional
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.
redirectUrlString(255)Required
Redirect URL after subscription or payment handling.
payCancelUrlString(255)Required
Redirect URL when the shopper cancels payment.
payResultUrlString(512)Required
Payment result page URL that the customer is redirected to after the initial payment completes.
paymentNotifyUrlString(255)Optional
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.
remarkString(255)Optional
Merchant extension field.
languageString(12)Optional
Interaction language.
tradeCountryString(2)Required
Country used for the PingPong checkout.
shopperIPString(128)Required
User's IP address for placing the order, supports IPv4 format.
merchantSourceString(64)Conditional
Site-building platform identifier when applicable.
merchantRequestBillDescriptorString(22)Optional
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.
customerIdString(64)Required
PingPong customer ID. Create the customer first via the Create Customer API. Sandbox verified (2026-10-21): if omitted, 102000 customerId: must not be blank is returned.
paymentMethodsArrayOptional
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

Request Body Example

{
  "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"
    }
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

periodObjectRequired
Subscription billing cycle.
- countIntegerRequired
  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.
- unitStringRequired
  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.
trialObjectOptional
Trial settings.
- startAtString(10)Optional
  Trial start time as a 10-digit second-level timestamp string.
- endAtString(10)Conditional
  Trial end time as a 10-digit second-level timestamp string.
- periodDaysIntegerConditional
  Trial duration in days.
autoRecoveryObjectOptional
Automatic retry settings.
- enabledBooleanOptional
  Whether automatic retry is enabled. Automatic retry is enabled by default.
  true: retry enabled
  false: retry disabled
flatPriceObjectRequired
Recurring amount and currency for each formal billing cycle.
- amountString(12)Required
  Subscription payment amount.
- currencyString(3)Required
  Subscription billing currency.
discountObjectOptional
Current effective subscription discount configuration. Not returned when no discount is configured.
- typeString(32)Required
  Discount type. Valid values:
  fixedAmount: fixed-amount discount.
  percentage: percentage discount.
- amountOffString(12)Conditional
  Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff.
- percentOffString(12)Conditional
  Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff.
- durationCountString(12)Required
  Number of formal billing cycles for which the discount applies, excluding the trial period.
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
requestIdString(64)Required
Merchant request ID.
subscriptionIdString(64)Required
PingPong subscription ID.
statusString(32)Required
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.
redirectUrlString(255)Optional
Redirect URL after checkout payment is completed.
startAtString(10)Optional
Subscription start time as a 10-digit second-level timestamp string.
endAtString(10)Optional
Subscription end time as a 10-digit second-level timestamp string.
notifyUrlString(255)Required
Subscription notification URL.
totalPeriodCountIntegerOptional
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.
tokenStringRequired
Subscription checkout session token.
innerJsUrlStringRequired
JS SDK URL.
paymentUrlStringRequired
Hosted payment URL.
partnerTransactionIdString(64)Optional
First payment transaction ID, corresponding to merchantTransactionId in the request.
actionObjectOptional
Follow-up action required from the buyer, containing jsSdkUrl / paymentRedirectUrl etc.; an empty object when no further action is needed.
resultCodeString(6)Required
Acceptance result code; 000000 indicates success.
resultMessageString(256)Required
Acceptance result description.

Request Body Example

{
  "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"
}

Customer APIs

Invoice APIs

Create Subscription Checkout Session

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example