---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/invoice/overview/index.md
description: >-
  Invoice V4 API 提供买家（Customer）、票据（Invoice）与支付凭证（Receipt）管理能力，并配套票据与买家事件的
  Webhook 通知。
---
Invoice V4 API 提供**买家（Customer）**、**票据（Invoice）**与**支付凭证（Receipt）**的管理能力，并配套票据与买家事件的 Webhook 通知，适用于订阅 billing、 invoice 开具与支付凭证归档等场景。

## 接口列表

### 买家接口

| 接口 | 路径 | 说明 |
| --- | --- | --- |
| 创建买家 | `POST /v4/customers/create` | 根据商户侧买家标识创建买家，返回 PingPong 买家 ID |
| 更新买家 | `POST /v4/customers/update` | 按 PingPong 买家 ID 更新买家资料，仅更新传入字段 |
| 查询买家 | `POST /v4/customers/query` | 按 PingPong 买家 ID 查询买家资料 |

### 票据接口

| 接口 | 路径 | 说明 |
| --- | --- | --- |
| 票据详情 | `POST /v4/invoices/query` | 按票据 ID 查询票据详情，含金额、买家、商户快照、支付信息与下载链接 |
| 票据下载 | `POST /v4/invoices/download` | 生成并获取票据 PDF 下载链接 |
| 凭证详情 | `POST /v4/invoices/receipt/query` | 按凭证 ID 查询支付凭证详情，含支付与退款记录 |
| 凭证下载 | `POST /v4/invoices/receipt/download` | 生成并获取凭证 PDF 下载链接 |

### Webhook 通知

| 事件 | 触发时机 | 报文说明 |
| --- | --- | --- |
| `INVOICE_CREATED` | 票据创建完成（DRAFT 状态） | [票据创建通知](/notes/zh/notify/invoice/created/) |
| `INVOICE_FINALIZED` | 票据定稿，单据号分配完成 | [票据定稿通知](/notes/zh/notify/invoice/finalized/) |
| `CUSTOMER_UPDATED` | 买家资料更新成功 | [买家更新通知](/notes/zh/notify/invoice/customerUpdated/) |
| `RECEIPT_CREATED` | 正向支付成功，支付凭证生成 | [凭证创建通知](/notes/zh/notify/invoice/receiptCreated/) |

## 通用约定

- **金额**：十进制字符串（如 `12.34`）。
- **时间**：10 位秒级时间戳字符串（如 `1792473374`）。

## 公共请求参数

所有接口顶层均需携带以下公共参数：

| 字段名称 | 是否必填 | 说明 |
| --- | --- | --- |
| clientId | 必填 | 商户号 |
| accId | 必填 | 店铺号 |
| signType | 必填 | 签名类型，MD5 |
| sign | 必填 | 签名值，沿用 V4 [签名规约](/notes/zh/onlinePayment/developer/sign/) |
| version | 必填 | 接口版本，固定为 `4.0` |
| bizContent | 必填 | 业务参数 JSON 字符串（内容见各接口 bizContent 参数） |

## 公共响应参数

| 字段名称 | 说明 |
| --- | --- |
| clientId | 商户号 |
| accId | 店铺号 |
| signType | 签名类型 |
| sign | 签名值 |
| code | 响应码：成功 `000000`；失败透传业务错误码（`102000` 参数错误 / `500003` 资源不存在 / `910001` 业务校验失败 / `910005` 当前状态不支持该操作 / `910008` 存在处理中的变更任务 / `500000` 系统异常等） |
| description | 响应描述 |
| bizContent | 业务响应 JSON 字符串（内容见各接口 bizContent 响应） |

::: warning 注意
本模块接口版本固定为 `4.0`（与本站支付类接口的 `1.0` 不同），响应时间为 ISO 8601 UTC 格式（支付/订阅接口为时间戳），接入时请注意区分。
:::

## Webhook 通用说明

- 商户按事件配置回调地址，**同一商户同一事件仅支持一个回调 URL**；未配置的事件不推送。
- 统一报文信封（全部事件一致）：`clientId`、`accId`、`signType`、`bizContent`、`sign`。
- `bizContent` 内首字段 `notifyType` 标识事件类型，业务字段均为 camelCase，时间字段为秒级时间戳数字。
- 商户处理成功返回 HTTP 2xx；非 2xx 或响应体为 `FAIL` 视为通知失败，系统将按策略重试。