---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/create/index.md
description: >-
  The Create Subscription (API Only) API lets merchants create a subscription
  plan directly while submitting the first payment together with billing cycle,
  trial, customer and payment element data.
---
# Create Subscription (API Only)

```apidef
endpoint: POST /v4/subscriptions/create
name: Create Subscription (API Only)
summary: Create a subscription plan via API Only
tags: Subscription, API Only
```

The Create Subscription (API Only) API lets merchants create a subscription plan directly while submitting the first payment together with billing cycle, trial, customer and payment element data.

## 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. |
| └─ requestId | string | M | Unique merchant request ID. |
| └─ description | string | M | Description of the subscription plan, for example Youtube monthly menbership. |
| └─ redirectUrl | string | O | 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. |
| └─ startAt | string | O | Subscription start time as a 10-digit second-level timestamp string. If omitted, the current time is used by default. |
| └─ endAt | string | O | 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. |
| └─ notifyUrl | string | M | 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. |
| └─ payResultUrl | string | M | 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). |
| └─ period | object | M | Subscription billing duration. |
| └─ └─ 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 period 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 configuration. |
| └─ └─ 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. |
| └─ └─ amount | string | M | Recurring billing amount for each cycle. |
| └─ └─ currency | string | M | Recurring billing currency in ISO 4217 3-letter format. |
| └─ 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. |
| └─ paymentNotifyUrl | string | O | 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. |
| └─ remark | string | O | Merchant extension field returned as-is in the response. |
| └─ language | string | O | Interaction language. |
| └─ tradeCountry | string | M | Transaction country. Use an ISO 3166-1 alpha-2 two-letter country code. |
| └─ shopperIP | string | M | User's IP address for placing the order, supports IPv4 format. |
| └─ 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. If omitted, 102000 customerId: must not be blank is returned. |
| └─ paymentMethod | object | M | Payment method and payment details. |
| └─ └─ type | string | M | Payment method type. Currently supported values: scheme International credit card; ApplePay; GooglePay; Klarna; PayPal; |
| └─ └─ cardInfo | object | C | Card payment details. Required when using international cards. |
| └─ └─ └─ number | string | M | Card number. |
| └─ └─ └─ expireMonth | string | M | Card expiry month. |
| └─ └─ └─ expireYear | string | M | Card expiry year. |
| └─ └─ └─ holderFirstName | string | M | Cardholder first name. |
| └─ └─ └─ holderLastName | string | M | Cardholder last name. |
| └─ └─ └─ cvv | string | M | Card security code. |
| └─ jsGeneratedData | string | C | 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: /en/notes/risk/3ds/ for details. |
| └─ customer | object | O | Customer information. Not needed when customerId is provided; the customer profile referenced by customerId prevails. |
| └─ └─ 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_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\"}}"
}
```

## 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 |
| └─ flatPrice | object | Current recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | Actual recurring amount for each formal billing cycle of the subscription plan. |
| └─ └─ currency | string | Billing currency for formal subscription cycles, as a 3-letter ISO 4217 currency code. |
| └─ 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. |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ requestId | string | Unique 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.; |
| └─ 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; |
| └─ threeDContinue | string | Whether 3DS continuation is required. |
| └─ threeDUnionParams | object | 3DS processing parameters. |
| └─ └─ threeDSMethodData | string | 3DS Method data. |
| └─ └─ creq | string | 3DS Challenge request parameter. |
| └─ paymentMethod | object | Payment method details. |
| └─ └─ type | string | Payment method type. |
| └─ └─ cardInfo | object | Card information inside the payment method. |
| └─ └─ └─ firstSixDigits | string | First six digits of the card number. |
| └─ └─ └─ lastFourDigits | string | Last four digits of the card number. |
| └─ └─ └─ issuringBank | string | Issuing bank. |
| └─ └─ └─ isoCountry | string | Issuing country. |
| └─ └─ └─ paymentBrand | string | Payment brand. |
| └─ └─ └─ cardType | string | Card type. |
| └─ └─ └─ cardLevel | string | Card level. |
| └─ └─ └─ lastName | string | Cardholder last name. |
| └─ └─ └─ firstName | string | Cardholder first name. |
| └─ └─ └─ ipCountry | string | IP country. |
| └─ └─ └─ isoCountryA2 | string | ISO 3166-1 alpha-2 country code. |
| └─ cardInfo | object | Card information. |
| └─ └─ firstSixDigits | string | First six digits of the card number. |
| └─ └─ lastFourDigits | string | Last four digits of the card number. |
| └─ └─ issuringBank | string | Issuing bank. |
| └─ └─ isoCountry | string | Issuing country. |
| └─ └─ paymentBrand | string | Payment brand. |
| └─ └─ cardType | string | Card type. |
| └─ └─ cardLevel | string | Card level. |
| └─ └─ lastName | string | Cardholder last name. |
| └─ └─ firstName | string | Cardholder first name. |
| └─ └─ ipCountry | string | IP country. |
| └─ └─ isoCountryA2 | string | ISO 3166-1 alpha-2 country code. |
| └─ authenticationInfo | object | Payment authentication details. |
| └─ └─ threeDSecure | string | 3DS verification indicator. |
| └─ └─ cvvResult | string | CVV verification result, Y/N. |
| └─ └─ avsResult | string | AVS verification result. |
| └─ action | object | Follow-up payment action details. |
| └─ └─ type | string | Next action type. |
| └─ └─ qrCode | string | QR code content. |
| └─ └─ qrUrl | string | QR code URL. |
| └─ └─ paymentRedirectUrl | string | Payment redirect URL. |
| └─ └─ jsSdkUrl | string | JS SDK URL. |
| └─ issuerInfo | object | Issuer response information. |
| └─ └─ issuerResultCode | string | Issuer result code. |
| └─ └─ issuerResultMsg | string | Issuer result message. |
| └─ partnerTransactionId | string | Merchant transaction ID of the initial/current period payment, formatted as subscriptionId_P{period} . |
| └─ transactionId | string | PingPong transaction ID of the initial/current period payment. |
| └─ remark | string | Merchant extension field, echoed as-is. |
| └─ resultCode | string | Business result code. |
| └─ resultMessage | string | Business result message. |

### Response Example

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