---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/query/index.md
description: 查询订阅详情接口用于获取订阅计划当前状态、周期信息、试用期配置以及已完成支付记录摘要等信息。
---
# 查询订阅详情

```apidef
endpoint: POST /v4/subscriptions/query
name: 查询订阅详情
summary: 查询订阅计划详情
tags: Subscription, Query
```

查询订阅详情接口用于获取订阅计划当前状态、周期信息、试用期配置以及已完成支付记录摘要等信息。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| 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 | C | 商户定义的订阅计划的唯一ID，和 subscriptionId 至少上传一个。 |
| └─ subscriptionId | string | C | PingPong 订阅单号，和 merchantSubscriptionId 至少上传一个。 |
| └─ requestId | string | M | 商户请求唯一编号。 |

### 请求示例

```json
{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_M_202606110001\",\"subscriptionId\":\"PP_SUB_001\",\"requestId\":\"REQ_SUB_QUERY_001\"}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| 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 | 商户请求唯一编号。 |
| └─ description | string | 订阅计划描述。 |
| └─ status | string | 订阅计划状态。有效值包括： PENDING 订阅已创建，但尚未进入正式生效阶段。; IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。; ACTIVE 订阅当前正常生效中，用户有权使用服务。; PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。; CANCELLED 订阅已终止，不再继续自动续费。; |
| └─ cancelReason | string | 订阅状态为 CANCELLED 时返回，表示订阅取消原因。 USER_REQUESTED 用户取消; MERCHANT_REQUESTED 商户取消; PAYMENT_RETRY_EXHAUSTED 自动重试结束; PLAN_ENDED 订阅到期结束; |
| └─ currentPeriod | integer | 当前所在周期， 0 、 1 、 2 、 3 ...，其中 0 代表试用期。 |
| └─ startAt | string | 订阅开始时间，10 位秒级时间戳字符串。 |
| └─ endAt | string | 订阅结束时间，10 位秒级时间戳字符串。 |
| └─ notifyUrl | string | 订阅通知地址。 |
| └─ 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 关闭重试; |
| └─ paymentRecords | array | 简版支付记录列表。 |
| └─ └─ period | integer | 所属订阅期次。 |
| └─ └─ merchantTransactionId | string | 该期对应的商户交易单号。 |
| └─ refundRecords | array | 退款记录列表。 |
| └─ └─ merchantRefundId | string | 退款订单号。 |
| └─ └─ originalMerchantTransactionId | 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_QUERY_001\",\"description\":\"monthly membership plan\",\"status\":\"ACTIVE\",\"cancelReason\":\"\",\"currentPeriod\":1,\"startAt\":\"1785152760\",\"endAt\":\"1816688760\",\"notifyUrl\":\"https://merchant.example.com/notify/subscription\",\"duration\":{\"periodCount\":1,\"periodUnit\":\"MONTH\"},\"trial\":{\"startAt\":\"1785152760\",\"endAt\":\"1785757560\",\"periodDays\":7,\"amount\":\"0.00\",\"currency\":\"USD\"},\"autoRecovery\":{\"enabled\":true},\"paymentRecords\":[{\"period\":1,\"merchantTransactionId\":\"SUB-1234567890abcdef_P1\"}],\"refundRecords\":[{\"merchantRefundId\":\"SREF-1234567890\",\"originalMerchantTransactionId\":\"SUB-1234567890abcdef_P1\"}],\"resultCode\":\"000000\",\"resultMessage\":\"SUCCESS\"}",
  "code": "000000",
  "description": "SUCCESS"
}
```