---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/cancel/index.md
description: 取消订阅接口用于终止一个已有的订阅计划，支持立即取消，也支持在当前周期结束后取消。
---
# 取消订阅

```apidef
endpoint: POST /v4/subscriptions/cancel
name: 取消订阅
summary: 取消订阅计划
tags: Subscription, Management
```

取消订阅接口用于终止一个已有的订阅计划，支持立即取消，也支持在当前周期结束后取消。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| accId | string | M | 店铺唯一标识 |
| clientId | string | M | PingPong 商户号 |
| signType | string | M | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | M | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| version | string | M | 版本号，当前固定为1.0，后续随接口变动可能有调整 |
| bizContent | string | M | 请求参数的集合，最大长度不限，除公共请求参数外所有请求参数都必须放在这个参数中传递，格式：JSON字符串。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ merchantSubscriptionId | string | M | 商户定义的订阅计划的唯一ID。 |
| └─ requestId | string | M | 商户请求唯一编号。 |
| └─ cancelAtPeriodEnd | boolean | O | 传入 true 表示该订阅计划不会立即取消，而是在当前计费周期结束时自动取消；在周期结束前，订阅仍按当前状态继续生效，商户应继续提供服务。传入 false 表示按本次请求立即执行取消或按其他变更参数处理。默认为 false 。 |
| └─ prorationMode | string | O | 按比例计费模式。当 cancelAtPeriodEnd 为 false 时生效。不填默认 PRORATED 。有效值包括： PRORATED ：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。; NONE ：不考虑未兑现时间的残值。; CUSTOM ：商户自定义本次取消产生的退款金额，而不让系统按剩余周期自动计算退款金额。; |
| └─ customRefundAmount | string | C | 当 prorationMode 为 CUSTOM 时必传，表示商户自定义的本次取消退款金额。该金额仅用于本次取消请求对应的退款处理。 |
| └─ customCurrency | string | C | 当 prorationMode 为 CUSTOM 时必传，表示商户自定义退款金额对应的币种。使用 ISO 4217 三位币种代码。 |
| └─ refundNotificationUrl | string | O | 本次取消若产生退款，用于接收该笔退款结果的异步通知地址；仅对本次取消请求生效。 |

### 请求示例

```json
{
  "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\",\"refundNotificationUrl\":\"https://merchant.example.com/refund/notify\"}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| accId | string | 店铺唯一标识 |
| clientId | string | PingPong 商户号 |
| signType | string | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| code | string | 结果状态码，见附录状态码表: /notes/zh/appendix/successCodeList/ |
| description | string | 结果描述 |
| bizContent | string | 业务响应参数。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ merchantSubscriptionId | string | 商户定义的订阅计划的唯一ID。 |
| └─ subscriptionId | string | PingPong 订阅单号。 |
| └─ requestId | string | 商户请求唯一编号。 |
| └─ status | string | 订阅计划状态。有效值包括： PENDING 订阅已创建，但尚未进入正式生效阶段。; IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。; ACTIVE 订阅当前正常生效中，用户有权使用服务。; PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。; CANCELLED 订阅已终止，不再继续自动续费。; |
| └─ cancelReason | string | 订阅状态为 CANCELLED 时返回，表示订阅取消原因。 USER_REQUESTED 用户取消; MERCHANT_REQUESTED 商户取消; PAYMENT_RETRY_EXHAUSTED 自动重试结束; PLAN_ENDED 订阅到期结束; |
| └─ redirectUrl | string | 订阅相关跳转地址。 |
| └─ notifyUrl | string | 订阅通知地址。 |
| └─ startAt | string | 订阅开始时间，10 位秒级时间戳字符串。 |
| └─ endAt | string | 订阅结束时间，10 位秒级时间戳字符串。 |
| └─ duration | object | 订阅周期信息。 |
| └─ └─ periodCount | integer | 订阅周期数量，必须大于等于 1。例如，如果 periodUnit 的值为 MONTH ， periodCount 的值为 1 ，则表示订阅周期为一个月。支持 1 - 无限。 |
| └─ └─ periodUnit | string | 订阅周期单位类型，有效值包括： YEAR ：表示订阅周期以年为单位。; MONTH ：表示订阅周期以月为单位。; WEEK ：表示订阅周期以周为单位。; DAY ：表示订阅周期以天为单位。; |
| └─ trial | object | 试用期信息。 |
| └─ └─ startAt | string | 试用期开始时间，10 位秒级时间戳字符串。 |
| └─ └─ endAt | string | 试用期结束时间，10 位秒级时间戳字符串。 |
| └─ └─ periodDays | integer | 试用期持续天数。 |
| └─ └─ amount | string | 试用期扣款金额。 |
| └─ └─ currency | string | 试用期扣款币种。 |
| └─ autoRecovery | object | 自动重试配置。 |
| └─ └─ enabled | boolean | 是否开启自动重试，默认自动开启。 true 开启重试; false 关闭重试; |
| └─ cancelAtPeriodEnd | boolean | 是否将在本次计费周期结束时取消该订阅计划； true 表示周期结束时取消。 |
| └─ cancelAt | string | 实际取消时间。 |
| └─ resultCode | string | 业务处理结果码。 |
| └─ resultMessage | string | 业务处理结果描述。 |

### 响应示例

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