---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/invoice/query/index.md
description: 票据详情接口按票据 ID 查询票据，返回金额、买家、商户快照、支付信息与下载链接；订阅场景额外返回账单所属周期。
---
# 票据详情

```apidef
endpoint: POST /v4/invoices/query
name: 票据详情
summary: 按 invoiceId 查询票据详情
tags: Invoice
```

票据详情接口按票据 ID 查询票据，返回金额、买家、商户快照、支付信息与下载链接；订阅场景额外返回账单所属周期。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| clientId | string | M | 商户号。 |
| accId | string | M | 店铺号。 |
| signType | string | M | 签名类型，MD5，具体见本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏。 |
| sign | string | M | 签名值，沿用 V4 签名规范，所有参数均参与签名。 |
| version | string | M | 接口版本，固定为 4.0 。 |
| bizContent | string | M | 业务参数 JSON 字符串，除公共请求参数外所有请求参数都必须放在这个参数中传递。 该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ requestId | string | M | 唯一请求号，全局唯一。 |
| └─ invoiceId | string | M | 票据 ID。 |

### 请求示例

```json
{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "4.0",
  "bizContent": "{\"requestId\":\"req_20260507_0011\",\"invoiceId\":\"INV-260507100000000001\"}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| clientId | string | 商户号。 |
| accId | string | 店铺号。 |
| signType | string | 签名类型。 |
| sign | string | 签名值，沿用 V4 签名规范验签。 |
| code | string | 响应码：成功 000000 ；失败透传业务错误码（ 102000 参数错误 / 500003 资源不存在 / 910001 业务校验失败 / 910005 当前状态不支持该操作 / 910008 存在处理中的变更任务 / 500000 系统异常等）。 |
| description | string | 响应描述。 |
| bizContent | string | 业务响应 JSON 字符串。 该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ requestId | string | 唯一请求号，回显请求。 |
| └─ invoiceId | string | 票据 ID。 |
| └─ invoiceNumber | string | 票据单据号，定稿后分配。 |
| └─ version | integer | 票据版本号，每次重渲染递增。 |
| └─ status | string | 票据状态： DRAFT ：草稿，创建后未定稿，可更新或作废。; FINALIZED ：已定稿，单据号已分配，可下载。; VOID ：已作废。; 沙箱实测：票据状态会联动支付链路，可能返回 PAYMENT_PENDING （扣款处理中）/ PAID / PARTIALLY_REFUNDED （退款挂在首期票据上）/ FULLY_REFUNDED 。 |
| └─ createdAt | string | 创建时间，10 位秒级时间戳字符串。 |
| └─ finalizedAt | string | 定稿时间，10 位秒级时间戳字符串。 |
| └─ paidAt | string | 支付完成时间，10 位秒级时间戳字符串。 |
| └─ currency | string | 币种，ISO 4217。 |
| └─ subtotal | string | 小计金额，十进制字符串。 |
| └─ total | string | 总金额，十进制字符串。 |
| └─ amountPaid | string | 已支付金额，十进制字符串。沙箱实测（2026-10-19）：票据未支付完成（PAYMENT_PENDING）时不返回该字段。 |
| └─ subscriptionDetail | object | 订阅信息对象，非订阅场景不返回。 |
| └─ └─ subscriptionId | string | PingPong 订阅号。 |
| └─ └─ partnerSubscriptionId | string | 商户侧订阅号。 |
| └─ └─ startAt | string | 账单所属周期起期，10 位秒级时间戳字符串。 |
| └─ └─ endAt | string | 账单所属周期止期，10 位秒级时间戳字符串。 |
| └─ customer | object | 买家对象，结构同买家接口: /notes/zh/subscription/invoice/customer/query/响应主体。 |
| └─ └─ customerId | string | PingPong 买家 ID。 |
| └─ └─ partnerCustomerId | string | 商户侧买家标识，用户在商户网站的会员 ID，同店铺内唯一。 |
| └─ └─ firstName | string | 名。 |
| └─ └─ lastName | string | 姓。 |
| └─ └─ companyName | string | 公司名。 |
| └─ └─ email | string | 邮箱。 |
| └─ └─ phone | string | 电话。 |
| └─ └─ address | object | 地址对象，结构同请求 address。 |
| └─ └─ └─ country | string | 国家二字码，ISO 3166 标准。 |
| └─ └─ └─ state | string | 州/省。 |
| └─ └─ └─ city | string | 城市。 |
| └─ └─ └─ postalCode | string | 邮编。 |
| └─ └─ └─ line1 | string | 地址行 1。 |
| └─ └─ └─ line2 | string | 地址行 2。 |
| └─ └─ language | string | 偏好语言地区。 |
| └─ └─ metadata | string | 商户自定义串。 |
| └─ └─ createdAt | string | 创建时间，10 位秒级时间戳字符串。 |
| └─ └─ updatedAt | string | 更新时间，10 位秒级时间戳字符串。 |
| └─ merchant | object | 开具方对象。 |
| └─ └─ legalName | string | 商户法定名称。 |
| └─ └─ address | object | 商户地址对象。 |
| └─ └─ └─ businessAddressEn | string | 商户英文营业地址。 |
| └─ └─ └─ postCode | string | 邮编。 |
| └─ └─ └─ country | string | 国家。沙箱实测返回国家全名（如 China ）。 |
| └─ └─ website | string | 商户网站。 |
| └─ payment | object | 支付信息对象。 |
| └─ └─ status | string | 支付状态。 |
| └─ └─ transactionId | string | PingPong 交易号。 |
| └─ └─ merchantTransactionId | string | 商户交易号。 |
| └─ └─ methodType | string | 支付方式：卡支付返回卡品牌（如 VISA ），其他方式为全大写 APM 名称（如 PAYNOW ）。 |
| └─ └─ transactionTime | string | 支付完成时间，ISO 8601 UTC。 |
| └─ download | object | 文件下载对象（当前版本详情响应可能不返回，建议直接通过票据下载: /notes/zh/subscription/invoice/download/接口获取下载链接）。 |
| └─ └─ url | string | 下载链接，30 天有效。 |
| └─ └─ expiresAt | string | 链接过期时间，10 位秒级时间戳字符串。 |
| └─ └─ version | integer | 文件对应票据版本。 |
| └─ └─ format | string | 文件格式，当前为 PDF 。 |

### 响应示例

```json
{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "code": "000000",
  "description": "SUCCESS",
  "bizContent": "{\"requestId\":\"req_20260507_0011\",\"invoiceId\":\"INV-260507100000000001\",\"invoiceNumber\":\"INV-2605070001\",\"version\":1,\"status\":\"FINALIZED\",\"createdAt\":\"2026-05-07T00:00:00Z\",\"finalizedAt\":\"2026-05-07T00:01:00Z\",\"paidAt\":\"2026-05-07T00:02:00Z\",\"currency\":\"USD\",\"subtotal\":\"10.00\",\"total\":\"10.00\",\"amountPaid\":\"10.00\",\"subscriptionDetail\":{\"subscriptionId\":\"SUB-2605070001\",\"partnerSubscriptionId\":\"sub_20260507_0002\",\"startAt\":\"2026-05-07T00:00:00Z\",\"endAt\":\"2026-06-07T00:00:00Z\"},\"customer\":{\"customerId\":\"CUS-260507100000000001\",\"partnerCustomerId\":\"USER_001\",\"firstName\":\"James\",\"lastName\":\"LeBron\",\"email\":\"james@example.com\"},\"merchant\":{\"legalName\":\"Example Pte. Ltd.\",\"address\":{\"businessAddressEn\":\"10 Marina Boulevard, Singapore\",\"postCode\":\"018983\",\"country\":\"SG\"},\"website\":\"https://merchant.example.com\"},\"payment\":{\"status\":\"SUCCESS\",\"transactionId\":\"260507100000000001\",\"merchantTransactionId\":\"M202605070001\",\"methodType\":\"CARD\",\"transactionTime\":\"2026-05-07T00:02:00Z\"},\"download\":{\"url\":\"https://example.com/invoice/INV-2605070001.pdf\",\"expiresAt\":\"2026-06-06T00:00:00Z\",\"version\":1,\"format\":\"PDF\"}}"
}
```