取消订阅

约 186 字小于 1 分钟

View as Markdown

2026-06-16

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
requestIdString(64)必填
商户请求唯一编号。
cancelAtPeriodEndBoolean可选
传入 true 表示该订阅计划不会立即取消，而是在当前计费周期结束时自动取消；在周期结束前，订阅仍按当前状态继续生效，商户应继续提供服务。传入 false 表示按本次请求立即执行取消或按其他变更参数处理。默认为 false。
prorationModeString(64)可选
按比例计费模式。当 cancelAtPeriodEnd 为 false 时生效。不填默认 NONE，即不按剩余周期自动折算退款。有效值包括：
- PRORATED：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。
- NONE：不考虑未兑现时间的残值。
- CUSTOM：商户自定义本次取消产生的退款金额，而不让系统按剩余周期自动计算退款金额。
customRefundAmountString(12)按条件选
当 prorationMode 为 CUSTOM 时必传，表示商户自定义的本次取消退款金额。该金额仅用于本次取消请求对应的退款处理。
customCurrencyString(3)按条件选
当 prorationMode 为 CUSTOM 时必传，表示商户自定义退款金额对应的币种。使用 ISO 4217 三位币种代码。
refundNotifyUrlString(255)可选
本次取消若产生退款，用于接收该笔退款结果的异步通知地址；仅对本次取消请求生效。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。

请求报文示例

{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "SUB_M_202606110001",
    "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

公共返回参数

bizContent

durationObject可选
trialObject可选
autoRecoveryObject可选
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
subscriptionIdString(64)必填
PingPong 订阅单号。
requestIdString(64)必填
商户请求唯一编号。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
cancelReasonString(64)可选
订阅状态为 CANCELLED 时返回，表示订阅取消原因。
- USER_REQUESTED 用户取消
- MERCHANT_REQUESTED 商户取消
- PAYMENT_RETRY_EXHAUSTED 自动重试结束
- PLAN_ENDED 订阅到期结束
redirectUrlString(255)可选
订阅相关跳转地址。
notifyUrlString(255)可选
订阅通知地址。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。
cancelAtPeriodEndBoolean可选
是否将在本次计费周期结束时取消该订阅计划；true 表示周期结束时取消。
cancelAtString(10)可选
实际取消时间。
resultCodeString必填
业务处理结果码。
resultMessageString必填
业务处理结果描述。

响应报文示例

{
  "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",
    "redirectUrl": "https://merchant.example.com/subscription/result",
    "notifyUrl": "https://merchant.example.com/notify/subscription",
    "startAt": "1785152760",
    "endAt": "1816688760",
    "duration": {
      "periodCount": 1,
      "periodUnit": "MONTH"
    },
    "trial": {
      "startAt": "1785152760",
      "endAt": "1785757560",
      "periodDays": 7,
      "amount": "0.00",
      "currency": "USD"
    },
    "autoRecovery": {
      "enabled": true
    },
    "cancelAtPeriodEnd": false,
    "cancelAt": "1785159999",
    "resultCode": "000000",
    "resultMessage": "SUCCESS"
  },
  "code": "000000",
  "description": "SUCCESS"
}