POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

• merchantSubscriptionIdString(64)Conditional

  Merchant-defined unique subscription plan ID. At least one of this field or subscriptionId is required.
• subscriptionIdString(64)Conditional

  PingPong subscription ID. At least one of this field or merchantSubscriptionId is required.
• requestIdString(64)Required

  Merchant request ID.
• cancelAtPeriodEndBooleanOptional

  If true is passed, the subscription will not be canceled immediately and will instead be canceled automatically at the end of the current billing cycle. Before the period ends, the subscription remains active in its current state and the merchant should continue providing service. If false is passed, the cancellation is handled immediately according to this request or other change parameters. Default is false.
• prorationModeString(64)Optional

  Proration mode for immediate cancellation. Only applicable when cancelAtPeriodEnd is false. Defaults to NONE if not provided, meaning no automatic refund is calculated based on the remaining period. Valid values include:

  • PRORATED: considers the residual value of the unused service time and calculates any extra charge or refund based on the remaining time.
  • NONE: does not consider the residual value of the unused service time.
  • CUSTOM: the merchant defines the refund amount generated by this cancellation instead of letting the system calculate the refund amount based on the remaining cycle automatically.

  
  Note: when cancelAtPeriodEnd is true (period-end cancellation), this field together with customRefundAmount, customCurrency, and refundNotifyUrl must all be omitted — even explicitly passing NONE is rejected with 102000 refund fields only support immediate cancellation. For period-end cancellation, omit the prorationMode field entirely.
• customRefundAmountString(12)Conditional

  Required when prorationMode is CUSTOM. Indicates the merchant-defined refund amount for this cancellation. This amount is used only for the refund handling associated with this cancellation request.
• customCurrencyString(3)Conditional

  Required when prorationMode is CUSTOM. Indicates the currency corresponding to the merchant-defined refund amount. Use a 3-letter ISO 4217 currency code.
• refundNotifyUrlString(255)Optional

  If this cancellation generates a refund, this URL is used to receive the asynchronous notification for that refund result. It applies only to this cancellation request.
  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.

Request Body Example

{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "SUB_M_202606110001",
    "subscriptionId": "SUB-1234567890abcdef",
    "requestId": "REQ_SUB_CANCEL_001",
    "cancelAtPeriodEnd": false,
    "prorationMode": "CUSTOM",
    "customRefundAmount": "0.33",
    "customCurrency": "USD",
    "refundNotifyUrl": "https://merchant.example.com/refund/notify"
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

• 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.
• flatPriceObjectOptional

  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.
• 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
• merchantSubscriptionIdString(64)Required

  Merchant-defined unique subscription plan ID.
• subscriptionIdString(64)Required

  PingPong subscription ID.
• requestIdString(64)Required

  Merchant request 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.
• cancelReasonString(64)Optional

  Returned when the subscription status is CANCELLED, indicating why the subscription ended.

  • user_requested: canceled by the user
  • merchant_requested: canceled by the merchant
  • payment_retry_exhausted: retry attempts exhausted
  • plan_ended: plan naturally ended
• notifyUrlString(255)Optional

  Subscription notification URL.
• startAtString(13)Optional

  Subscription start time as a 13-digit millisecond timestamp string.
• endAtString(13)Optional

  Subscription end time as a 13-digit millisecond timestamp string.
• 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.
• cancelAtPeriodEndBooleanOptional

  Whether the subscription plan will be canceled at the end of the current billing cycle. true means it will be canceled at period end.
• cancelAtString(13)Optional

  Actual cancellation time as a 13-digit millisecond timestamp string.
• resultCodeStringRequired

  Business result code.
• resultMessageStringRequired

  Business result message.

Request Body Example

{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "SUB_MER_001",
    "subscriptionId": "SUB-1234567890abcdef",
    "requestId": "REQ_SUB_CANCEL_001",
    "status": "CANCELLED",
    "cancelReason": "merchant_requested",
    "notifyUrl": "https://merchant.example.com/notify/subscription",
    "startAt": "1792152473588",
    "endAt": "1823688473588",
    "flatPrice": {
      "amount": "10.00",
      "currency": "USD"
    },
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "trial": {
      "startAt": "1785152760",
      "endAt": "1785757560",
      "periodDays": 7
    },
    "autoRecovery": {
      "enabled": true
    },
    "cancelAtPeriodEnd": false,
    "cancelAt": "1792152491606",
    "resultCode": "000000",
    "resultMessage": "SUCCESS"
  },
  "code": "000000",
  "description": "SUCCESS"
}

Previous pageUpdate Subscription

Next pageQuery Subscription