更新订阅

约 308 字大约 1 分钟

View as Markdown

2026-06-30

POST

📍如何选择站点？请参阅 API 端点地址

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

flatPriceObject可选
更新后的每个正式计费周期的扣款金额和币种。
- amountString(12)可选
  更新后的每期扣款金额。
- currencyString(3)可选
  更新后的每期扣款币种。
periodObject可选
更新后的订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
discountObject可选
订阅折扣变更。
不传：不修改当前折扣。
传 null：移除当前折扣。
传对象：覆盖当前折扣配置。
折扣仅面向后续正式计费周期，不作用于试用期，也不回溯已完成周期。
- typeString(32)必填
  折扣类型。有效值：
  fixedAmount：固定金额折扣。
  percentage：百分比折扣。
- amountOffString(12)按条件选
  固定金额减免。仅当 type 为 fixedAmount 时传入；与 percentOff 互斥。
- percentOffString(12)按条件选
  百分比减免值。仅当 type 为 percentage 时传入；与 amountOff 互斥。
- durationCountString(12)必填
  折扣持续的正式计费周期数，不包含试用期。
goodsObject可选
更新后的商品信息。纯撤销周期末取消（cancelAtPeriodEnd=false）等不变更商品的场景可不传。
- nameString(128)必填
  商品名称。
- descriptionString(255)可选
  商品描述。
- skuString(255)可选
  商品编号，产品SKU。
- unitPriceString(12)必填
  商品单价。注意：单个商品的 unitPrice × number 之和须与 flatPrice.amount 一致，否则返回 301012。
- unitTaxAmountString(12)按条件选
  单个商品税费，订单总金额包含税费时必填。
- taxRateString可选
  税率。
- totalDiscountAmountString按条件选
  单个商品总优惠金额，订单总金额涉及优惠时必填。
- numberString(12)必填
  商品购买数量。
- imgUrlString(255)必填
  商品主图链接。
- virtualProductString(1)可选
  是否是虚拟产品，虚拟商品（Y/N）。
- itemTypeString(1)可选
  商品类型，枚举值：1/2/3，对应含义如下：
  1 DIGITAL：数字商品
  2 PHYSICAL：实物商品
  3 SERVICE：服务
previewQuoteIdString(64)可选
预览接口返回的报价 ID。注意：走 quote 路径时，后续订阅变更通知中的 requestId 会归因到 Preview 的请求号而非本次 Update 请求号（已知问题），如需按 requestId 幂等关联请知悉。
merchantSubscriptionIdString(64)按条件选
商户定义的订阅计划的唯一ID。与 subscriptionId 至少传一个。
subscriptionIdString(64)按条件选
PingPong 订阅单号。与 merchantSubscriptionId 至少传一个。
requestIdString(64)必填
商户请求唯一编号。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
startAtString(64)可选
更新后的订阅开始时间，10 位秒级时间戳字符串。
endAtString(64)可选
更新后的订阅结束时间，10 位秒级时间戳字符串。
cancelAtPeriodEndBoolean可选
用于撤销已预约的周期末取消。若订阅已通过 Cancel 接口设置为周期末取消，可传入 false 取消该预约，使订阅继续按当前计划生效。该字段不用于发起取消；发起立即取消或周期末取消请调用 Cancel 接口。当前不支持通过 Update 将该字段改为 true。
descriptionString(256)必填
更新后的订阅计划描述。（网关强制必填）
effectiveModeString(64)必填
计划变更的生效模式。（网关强制必填）未填默认取 IMMEDIATE。若定义 NEXT_CYCLE，在下周期生效前，不允许再进行 update。有效值包括：
- IMMEDIATE 表示订阅计划变更即刻生效。
- NEXT_CYCLE 表示订阅计划下周期开始时生效。
billingActionString(64)必填
账单处理动作。（网关强制必填）有效值包括：
- IMMEDIATE_CHARGE_AND_KEEP_CYCLE：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。
- IMMEDIATE_CHARGE_AND_RESET_CYCLE：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。
- NEXT_CYCLE_CHARGE_KEEP_CYCLE：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。
prorationModeString(64)必填
按比例计费模式。（网关强制必填）不填默认 PRORATED。有效值包括：
- PRORATED：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。
- NONE：不考虑未兑现时间的残值。
- CUSTOM：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。
customAmountString(12)按条件选
当 prorationMode 为 CUSTOM 时上送的自定义金额。
customChargeDirectionString(32)按条件选
当 prorationMode 为 CUSTOM 时上送的金额方向，用于定义需要扣款还是退款。示例值为 REFUND。
customCurrencyString(3)按条件选
当 prorationMode 为 CUSTOM 时必传，自定义金额对应的币种（ISO 4217）。customAmount、customChargeDirection、customCurrency 三者在 CUSTOM 模式下缺一不可，否则报 910001。
expiresAtString(64)可选
本次变更支付的关单时间。用户需在该时间前完成支付以支持套餐变更。
redirectUrlString(255)必填
订阅修改涉及收银台/3DS 等交互时，成功后重定向回商户的地址，一般指商户的支付或订阅结果页。（网关强制必填）
refundNotifyUrlString(255)可选
商户自定义的退款结果异步通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
remarkString(255)可选
商户扩展字段。

请求报文示例

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

公共返回参数

bizContent

periodObject必填
变更后的订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
flatPriceObject必填
变更后订阅计划每个正式计费周期的扣款金额和币种。
- amountString(12)必填
  订阅计划每个正式计费周期的实际扣款金额。
- currencyString(3)必填
  订阅计划正式计费周期的扣款币种，使用三位字母的 ISO 4217 币种代码。
discountObject可选
变更后当前生效的订阅折扣配置；未配置折扣时不返回。
- typeString(32)必填
  折扣类型。有效值：
  fixedAmount：固定金额折扣。
  percentage：百分比折扣。
- amountOffString(12)按条件选
  固定金额减免。仅当 type 为 fixedAmount 时传入；与 percentOff 互斥。
- percentOffString(12)按条件选
  百分比减免值。仅当 type 为 percentage 时传入；与 amountOff 互斥。
- durationCountString(12)必填
  折扣持续的正式计费周期数，不包含试用期。
actionObject可选
支付后续动作信息。
- typeString可选
  下一步动作类型。
- qrCodeString可选
  二维码内容。
- qrUrlString可选
  二维码链接。
- paymentRedirectUrlString可选
  支付跳转地址。
- jsSdkUrlString可选
  JS SDK 地址。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
previewQuoteIdString(64)可选
本次订阅更新对应的预览报价 ID。
requestIdString(64)必填
商户请求唯一编号。
subscriptionIdString(64)必填
PingPong 订阅单号。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
chargeResultString(32)必填
本次变更涉及的扣款或退款处理结果。有效值包括：
- SUCCEEDED
- FAILED
- NOT_REQUIRED
- PENDING
chargeAmountString(12)按条件选
本次变更涉及的补扣或退款金额，仅返回正数。
chargeCurrencyString(3)按条件选
本次变更涉及的补扣或退款币种。
chargeDirectionString(32)可选
费用方向，示例值为 CHARGE 或 REFUND。
effectiveModeString(32)可选
计划变更的生效模式。未填默认取 IMMEDIATE。若定义 NEXT_CYCLE，在下周期生效前，不允许再进行 update。有效值包括：
- IMMEDIATE 表示订阅计划变更即刻生效。
- NEXT_CYCLE 表示订阅计划下周期开始时生效。
billingActionString(64)可选
账单处理动作。有效值包括：
- IMMEDIATE_CHARGE_AND_KEEP_CYCLE：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。
- IMMEDIATE_CHARGE_AND_RESET_CYCLE：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。
- NEXT_CYCLE_CHARGE_KEEP_CYCLE：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。
prorationModeString(32)必填
按比例计费模式。不填默认 PRORATED。有效值包括：
- PRORATED：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。
- NONE：不考虑未兑现时间的残值。
- CUSTOM：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。
effectivePlanVersionInteger可选
生效后的订阅计划版本号。
startAtString(13)可选
变更后订阅开始时间，13 位毫秒级时间戳字符串。
endAtString(13)可选
变更后订阅结束时间，13 位毫秒级时间戳字符串。
updatedAtString(13)可选
本次变更处理时间，13 位毫秒级时间戳字符串。
notifyUrlString(255)可选
订阅通知地址，回显。
cancelAtPeriodEndBoolean可选
变更后是否仍处于周期末取消预约状态。
currentPeriodInteger可选
当前所在周期，0 代表试用期。
proratedCurrencyString(3)可选
折算币种。
customAmountString(12)按条件选
prorationMode 为 CUSTOM 时回显的自定义金额。
customChargeDirectionString(32)按条件选
prorationMode 为 CUSTOM 时回显的金额方向。
customCurrencyString(3)按条件选
prorationMode 为 CUSTOM 时回显的自定义币种。
resultCodeString必填
业务处理结果码。
resultMessageString必填
业务处理结果描述。

响应报文示例

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

买家接口

票据接口

更新订阅

Request Body Parameters

请求报文示例

Responses Body Parameters

响应报文示例