POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

• flatPriceObjectOptional

  Updated recurring amount and currency for each formal billing cycle.

  • amountString(12)Optional

    Updated recurring amount for each billing cycle.
  • currencyString(3)Optional

    Updated recurring billing currency.
• periodObjectOptional

  Updated 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.
• discountObjectOptional

  Subscription discount change.

  • Omit: keep the current discount unchanged.
  • Pass null: remove the current discount.
  • Pass an object: replace the current discount configuration.

  The discount applies only to future formal billing cycles, not to the trial period or completed cycles.

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

  Updated goods information. Can be omitted when the change does not alter goods, e.g. merely revoking a scheduled period-end cancellation (cancelAtPeriodEnd=false).

  • 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
• previewQuoteIdString(64)Optional

  Preview quote ID returned by the preview API. Note: when using the quote path, the requestId in subsequent subscription change notifications is attributed to the Preview request instead of this Update request (known issue).
• 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

  Unique merchant request ID.
• 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.
• startAtString(64)Optional

  Updated subscription start time as a 10-digit second-level timestamp string.
• endAtString(64)Optional

  Updated subscription end time as a 10-digit second-level timestamp string.
• cancelAtPeriodEndBooleanOptional

  Used to revoke a scheduled period-end cancellation. If a subscription has already been scheduled for period-end cancellation through the Cancel API, pass false to cancel that schedule and keep the subscription active under the current plan. This field is not used to initiate cancellation; use the Cancel API for immediate or period-end cancellation. Setting this field to true through Update is currently not supported.
• descriptionString(256)Required

  Updated subscription description. (Mandatory per gateway validation.)
• effectiveModeString(64)Required

  Effective mode of the subscription change. Defaults to IMMEDIATE if not provided. If NEXT_CYCLE is specified, another update is not allowed before the change takes effect in the next billing cycle. Valid values include:

  • IMMEDIATE: the subscription change takes effect immediately.
  • NEXT_CYCLE: the subscription change takes effect at the beginning of the next billing cycle.
• billingActionString(64)Required

  Billing action. Valid values include:

  • IMMEDIATE_CHARGE_AND_KEEP_CYCLE: charge or refund immediately and keep the current billing anchor, frequency, and schedule.
  • IMMEDIATE_CHARGE_AND_RESET_CYCLE: charge or refund immediately and reset the billing anchor to the current time, allowing the billing frequency to change.
  • NEXT_CYCLE_CHARGE_KEEP_CYCLE: charge or refund on the next billing date while keeping the current billing frequency and schedule.
• prorationModeString(64)Required

  Proration mode. Defaults to PRORATED if not provided. 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 proration adjustment amount and direction for this change instead of letting the system calculate the price difference based on the remaining cycle automatically.
• customAmountString(12)Conditional

  Custom amount passed when prorationMode is CUSTOM.
• customChargeDirectionString(32)Conditional

  Amount direction passed when prorationMode is CUSTOM, used to indicate whether the change requires a charge or a refund. Example: REFUND.
• customCurrencyString(3)Conditional

  Required when prorationMode is CUSTOM: the currency of the custom amount (ISO 4217). customAmount, customChargeDirection and customCurrency are all mandatory in CUSTOM mode, otherwise 910001 is returned.
• expiresAtString(64)Optional

  Expiration time for the payment related to this update. The user must complete the payment before this time to support the plan change.
• redirectUrlString(255)Required

  Redirect URL back to the merchant after checkout/3DS interaction completes during the update, typically the merchant's payment or subscription result page. (Mandatory per gateway validation.)
• refundNotifyUrlString(255)Optional

  Merchant-defined asynchronous notification URL for refund results.
  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.

Request Body Example

{
  "clientId": "2023121216311410287",
  "accId": "2023121216311410287522",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "autocaseSubMerId_178401881002391785",
    "requestId": "AUTO988778009",
    "billingAction": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE",
    "effectiveMode": "IMMEDIATE",
    "flatPrice": {
      "amount": "60.00",
      "currency": "USD"
    },
    "description": "qa update template description",
    "goods": {
      "name": "Membership",
      "description": "Monthly membership",
      "sku": "SKU_SUB_001",
      "unitPrice": "60.00",
      "number": "1",
      "imgUrl": "https://merchant.example.com/goods/sub.png",
      "virtualProduct": "Y",
      "itemType": "3"
    },
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "discount": {
      "type": "fixedAmount",
      "amountOff": "5.00",
      "durationCount": "3"
    },
    "prorationMode": "CUSTOM",
    "customAmount": "58.06",
    "customChargeDirection": "REFUND",
    "customCurrency": "USD"
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

• periodObjectRequired

  Updated 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.
• flatPriceObjectRequired

  Updated 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 after the update. 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.
• 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.
• 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.
• previewQuoteIdString(64)Optional

  Preview quote ID associated with this subscription update.
• requestIdString(64)Required

  Unique merchant request ID.
• subscriptionIdString(64)Required

  PingPong subscription ID.
• merchantSubscriptionIdString(64)Required

  Merchant-defined unique subscription plan 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.
• chargeResultString(32)Required

  Processing result of the charge or refund caused by this update. Valid values include:

  • SUCCEEDED
  • FAILED
  • NOT_REQUIRED
  • PENDING
• chargeAmountString(12)Conditional

  Charge or refund amount involved in the change, returned as a positive number only.
• chargeCurrencyString(3)Conditional

  Currency of the charge or refund involved in the change.
• chargeDirectionString(32)Optional

  Charge direction. Example: CHARGE or REFUND.
• effectiveModeString(32)Optional

  Effective mode of the subscription change. Defaults to IMMEDIATE if not provided. If NEXT_CYCLE is specified, another update is not allowed before the change takes effect in the next billing cycle. Valid values include:

  • IMMEDIATE: the subscription change takes effect immediately.
  • NEXT_CYCLE: the subscription change takes effect at the beginning of the next billing cycle.
• billingActionString(64)Optional

  Billing action. Valid values include:

  • IMMEDIATE_CHARGE_AND_KEEP_CYCLE: charge or refund immediately and keep the current billing anchor, frequency, and schedule.
  • IMMEDIATE_CHARGE_AND_RESET_CYCLE: charge or refund immediately and reset the billing anchor to the current time, allowing the billing frequency to change.
  • NEXT_CYCLE_CHARGE_KEEP_CYCLE: charge or refund on the next billing date while keeping the current billing frequency and schedule.
• prorationModeString(32)Required

  Proration mode. Defaults to PRORATED if not provided. 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 proration adjustment amount and direction for this change instead of letting the system calculate the price difference based on the remaining cycle automatically.
• effectivePlanVersionIntegerOptional

  Effective subscription plan version after the update.
• startAtString(13)Optional

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

  Updated subscription end time as a 13-digit millisecond timestamp string.
• updatedAtString(13)Optional

  Time when this change was processed, as a 13-digit millisecond timestamp string.
• notifyUrlString(255)Optional

  Subscription notification URL, echoed.
• cancelAtPeriodEndBooleanOptional

  Whether the subscription remains scheduled for period-end cancellation after the change.
• currentPeriodIntegerOptional

  Current subscription period; 0 represents the trial period.
• proratedCurrencyString(3)Optional

  Currency of the prorated amount.
• customAmountString(12)Conditional

  Echoed custom amount when prorationMode is CUSTOM.
• customChargeDirectionString(32)Conditional

  Echoed amount direction when prorationMode is CUSTOM.
• customCurrencyString(3)Conditional

  Echoed custom currency when prorationMode is CUSTOM.
• resultCodeStringRequired

  Business result code.
• resultMessageStringRequired

  Business result message.

Request Body Example

{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "code": "910000",
  "description": "success",
  "sign": "5C3D9FF88B91C968ADFA8E834ACD59C9",
  "signType": "MD5",
  "bizContent": {
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "flatPrice": {
      "amount": "60.00",
      "currency": "USD"
    },
    "discount": {
      "type": "fixedAmount",
      "amountOff": "5.00",
      "durationCount": "3"
    },
    "resultCode": "910000",
    "billingAction": "IMMEDIATE_CHARGE_AND_RESET_CYCLE",
    "requestId": "REQ_SUB_UPDATE_001",
    "status": "ACTIVE",
    "chargeAmount": "60.00",
    "merchantSubscriptionId": "SUB_MER_001",
    "effectiveMode": "IMMEDIATE",
    "resultMessage": "success",
    "chargeDirection": "CHARGE",
    "effectivePlanVersion": 2,
    "previewQuoteId": "SUPD-2607150336100000001000141522",
    "chargeResult": "SUCCEEDED",
    "chargeCurrency": "USD",
    "subscriptionId": "SUB-1234567890abcdef",
    "prorationMode": "NONE",
    "proratedCurrency": "USD",
    "currentPeriod": 1,
    "cancelAtPeriodEnd": false,
    "notifyUrl": "https://merchant.example.com/notify/subscription",
    "startAt": "1792152613237",
    "endAt": "1823688613237",
    "updatedAt": "1792152608933",
    "action": {
      "type": "PAYMENT_REDIRECT_URL",
      "paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=TOKEN",
      "jsSdkUrl": "https://payssr-cdn.pingpongx.com/acquirer-checkout-web/sandbox/pp-checkout.js?token=TOKEN"
    }
  }
}

Previous pagePreview Subscription Update

Next pageCancel Subscription