Create Subscription (API Only)

About 178 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 duration.
- 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 period 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 configuration.
- 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
  Recurring billing amount for each cycle.
- currencyString(3)Required
  Recurring billing currency in ISO 4217 3-letter format.
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.
paymentMethodObjectRequired
Payment method and payment details.
- typeString(32)Required
  Payment method type. Currently supported values:
  scheme International credit card
  ApplePay
  GooglePay
  Klarna
  PayPal
- cardInfoObjectConditional
  Card payment details. Required when using international cards.
  - numberStringRequired
    Card number.
  - expireMonthString(2)Required
    Card expiry month.
  - expireYearString(4)Required
    Card expiry year.
  - holderFirstNameStringRequired
    Cardholder first name.
  - holderLastNameStringRequired
    Cardholder last name.
  - cvvStringRequired
    Card security code.
customerObjectOptional
Customer information. Not needed when customerId is provided; the customer profile referenced by customerId prevails.
- 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.
requestIdString(64)Required
Unique merchant request ID.
descriptionString(256)Required
Description of the subscription plan, for example Youtube monthly menbership.
redirectUrlString(255)Optional
Redirect URL that requires merchant handling during the subscription process, typically a 3DS challenge page or a wallet authorization binding page. Sandbox verified (2026-10-21): optional for creation; recommended when the first payment may trigger 3DS or authorization redirects.
startAtString(10)Optional
Subscription start time as a 10-digit second-level timestamp string. If omitted, the current time is used by default.
endAtString(10)Optional
Subscription end time as a 10-digit second-level timestamp string. A merchant-specified end time remains supported. If neither an end time nor a total cycle count is specified, the subscription renews indefinitely.
notifyUrlString(512)Required
Subscription plan 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.
payResultUrlString(512)Required
Payment result page URL that the customer is redirected to after the initial payment completes. Sandbox verified (2026-10-21): required; absence returns `payResultUrl:must not be blank` (102000).
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.
paymentNotifyUrlString(255)Optional
Payment result notification URL.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443, HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications.
remarkString(255)Optional
Merchant extension field returned as-is in the response.
languageString(12)Optional
Interaction language.
tradeCountryString(2)Required
Transaction country. Use an ISO 3166-1 alpha-2 two-letter country code.
shopperIPString(64)Required
User's IP address for placing the order, supports IPv4 format.
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. If omitted, 102000 customerId: must not be blank is returned.
jsGeneratedDataString(256)Conditional
Card payments must integrate the risk control component. Card payments need to pass this value. If acquisition fails, an empty string can be passed without blocking the payment flow. By embedding the risk control component provided by PingPong, obtain the browser-related JSON string and pass it in this parameter. Used by merchants integrated with the risk control plugin. See the 3DS Integration Guide for details.

Request Body Example

{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "SUB_M_202606110001",
    "requestId": "REQ_SUB_CREATE_001",
    "description": "Monthly membership subscription",
    "redirectUrl": "https://merchant.example.com/subscription/return",
    "payResultUrl": "https://merchant.example.com/subscription/result",
    "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": "fixedAmount",
      "amountOff": "1.00",
      "durationCount": "3"
    },
    "paymentNotifyUrl": "https://merchant.example.com/notify/payment",
    "remark": "test subscription",
    "language": "en",
    "tradeCountry": "US",
    "shopperIP": "8.8.8.8",
    "merchantRequestBillDescriptor": "TEST SUB",
    "customerId": "CUS-260507100000000001",
    "paymentMethod": {
      "type": "scheme",
      "cardInfo": {
        "number": "4111111111111111",
        "expireMonth": "12",
        "expireYear": "2030",
        "holderFirstName": "John",
        "holderLastName": "Smith",
        "cvv": "123"
      }
    },
    "jsGeneratedData": "JS_GENERATED_DATA",
    "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",
      "district": "SOMA"
    },
    "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

flatPriceObjectRequired
Current recurring amount and currency for each formal billing cycle.
- amountString(12)Required
  Actual recurring amount for each formal billing cycle of the subscription plan.
- currencyString(3)Required
  Billing currency for formal subscription cycles, as a 3-letter ISO 4217 currency code.
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.
periodObjectOptional
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
threeDUnionParamsObjectOptional
3DS processing parameters.
- threeDSMethodDataStringOptional
  3DS Method data.
- creqStringOptional
  3DS Challenge request parameter.
paymentMethodObjectOptional
Payment method details.
- typeString(32)Optional
  Payment method type.
- cardInfoObjectOptional
  Card information inside the payment method.
  - firstSixDigitsStringOptional
    First six digits of the card number.
  - lastFourDigitsStringOptional
    Last four digits of the card number.
  - issuringBankStringOptional
    Issuing bank.
  - isoCountryStringOptional
    Issuing country.
  - paymentBrandStringOptional
    Payment brand.
  - cardTypeStringOptional
    Card type.
  - cardLevelStringOptional
    Card level.
  - lastNameStringOptional
    Cardholder last name.
  - firstNameStringOptional
    Cardholder first name.
  - ipCountryStringOptional
    IP country.
  - isoCountryA2StringOptional
    ISO 3166-1 alpha-2 country code.
cardInfoObjectOptional
Card information.
- firstSixDigitsStringOptional
  First six digits of the card number.
- lastFourDigitsStringOptional
  Last four digits of the card number.
- issuringBankStringOptional
  Issuing bank.
- isoCountryStringOptional
  Issuing country.
- paymentBrandStringOptional
  Payment brand.
- cardTypeStringOptional
  Card type.
- cardLevelStringOptional
  Card level.
- lastNameStringOptional
  Cardholder last name.
- firstNameStringOptional
  Cardholder first name.
- ipCountryStringOptional
  IP country.
- isoCountryA2StringOptional
  ISO 3166-1 alpha-2 country code.
authenticationInfoObjectOptional
Payment authentication details.
- threeDSecureStringOptional
  3DS verification indicator.
- cvvResultStringOptional
  CVV verification result, Y/N.
- avsResultStringOptional
  AVS verification result.
actionObjectOptional
Follow-up payment action details.
- typeStringOptional
  Next action type.
- qrCodeStringOptional
  QR code content.
- qrUrlStringOptional
  QR code URL.
- paymentRedirectUrlStringOptional
  Payment redirect URL.
- jsSdkUrlStringOptional
  JS SDK URL.
issuerInfoObjectOptional
Issuer response information.
- issuerResultCodeStringOptional
  Issuer result code.
- issuerResultMsgStringOptional
  Issuer result message.
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
requestIdString(64)Required
Unique 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.
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)Optional
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.
threeDContinueString(32)Optional
Whether 3DS continuation is required.
partnerTransactionIdString(64)Optional
Merchant transaction ID of the initial/current period payment, formatted as subscriptionId_P{period}.
transactionIdString(64)Optional
PingPong transaction ID of the initial/current period payment.
remarkString(255)Optional
Merchant extension field, echoed as-is.
resultCodeStringRequired
Business result code.
resultMessageStringRequired
Business result message.

Request Body Example

{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "flatPrice": {
      "amount": "9.99",
      "currency": "USD"
    },
    "discount": {
      "type": "fixedAmount",
      "amountOff": "1.00",
      "durationCount": "3"
    },
    "merchantSubscriptionId": "SUB_MER_001",
    "requestId": "REQ_SUB_CREATE_001",
    "subscriptionId": "SUB-1234567890abcdef",
    "status": "ACTIVE",
    "resultCode": "000000",
    "resultMessage": "Transaction succeeded",
    "partnerTransactionId": "SUB-1234567890abcdef_P1",
    "transactionId": "26101600000352284454",
    "remark": "test subscription",
    "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
    },
    "threeDContinue": "Y",
    "threeDUnionParams": {
      "threeDSMethodData": "THREEDS_METHOD_DATA",
      "creq": "CREQ_VALUE"
    },
    "paymentMethod": {
      "type": "CARD",
      "cardInfo": {
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "issuringBank": "CHASE",
        "isoCountry": "US",
        "paymentBrand": "VISA",
        "cardType": "CREDIT",
        "cardLevel": "PLATINUM",
        "lastName": "Lebron",
        "firstName": "James",
        "ipCountry": "US",
        "isoCountryA2": "US"
      }
    },
    "cardInfo": {
      "firstSixDigits": "411111",
      "lastFourDigits": "1111",
      "issuringBank": "CHASE",
      "isoCountry": "US",
      "paymentBrand": "VISA",
      "cardType": "CREDIT",
      "cardLevel": "PLATINUM",
      "lastName": "Lebron",
      "firstName": "James",
      "ipCountry": "US",
      "isoCountryA2": "US"
    },
    "authenticationInfo": {
      "threeDSecure": "Y",
      "cvvResult": "Y",
      "avsResult": "U"
    },
    "action": {
      "type": "PAYMENT_REDIRECT_URL",
      "qrCode": "QR_CODE_CONTENT",
      "qrUrl": "https://merchant.example.com/qr.png",
      "paymentRedirectUrl": "https://merchant.example.com/payment/redirect",
      "jsSdkUrl": "https://pay-cdn.pingpongx.com/sdk.js"
    },
    "issuerInfo": {
      "issuerResultCode": "00",
      "issuerResultMsg": "APPROVED"
    }
  },
  "code": "000000",
  "description": "SUCCESS"
}

Customer APIs

Invoice APIs

Create Subscription (API Only)

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example