Invoice 概述
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 状态） | 票据创建通知 |
INVOICE_FINALIZED | 票据定稿，单据号分配完成 | 票据定稿通知 |
CUSTOMER_UPDATED | 买家资料更新成功 | 买家更新通知 |
RECEIPT_CREATED | 正向支付成功，支付凭证生成 | 凭证创建通知 |
通用约定
- 金额：十进制字符串（如
12.34）。 - 时间：10 位秒级时间戳字符串（如
1792473374）。
公共请求参数
所有接口顶层均需携带以下公共参数：
| 字段名称 | 是否必填 | 说明 |
|---|---|---|
| clientId | 必填 | 商户号 |
| accId | 必填 | 店铺号 |
| signType | 必填 | 签名类型，MD5 |
| sign | 必填 | 签名值，沿用 V4 签名规约 |
| version | 必填 | 接口版本，固定为 4.0 |
| bizContent | 必填 | 业务参数 JSON 字符串（内容见各接口 bizContent 参数） |
公共响应参数
| 字段名称 | 说明 |
|---|---|
| clientId | 商户号 |
| accId | 店铺号 |
| signType | 签名类型 |
| sign | 签名值 |
| code | 响应码：成功 000000；失败透传业务错误码（102000 参数错误 / 500003 资源不存在 / 910001 业务校验失败 / 910005 当前状态不支持该操作 / 910008 存在处理中的变更任务 / 500000 系统异常等） |
| description | 响应描述 |
| bizContent | 业务响应 JSON 字符串（内容见各接口 bizContent 响应） |
注意
本模块接口版本固定为 4.0（与本站支付类接口的 1.0 不同），响应时间为 ISO 8601 UTC 格式（支付/订阅接口为时间戳），接入时请注意区分。
Webhook 通用说明
- 商户按事件配置回调地址，同一商户同一事件仅支持一个回调 URL；未配置的事件不推送。
- 统一报文信封（全部事件一致）：
clientId、accId、signType、bizContent、sign。 bizContent内首字段notifyType标识事件类型，业务字段均为 camelCase，时间字段为秒级时间戳数字。- 商户处理成功返回 HTTP 2xx；非 2xx 或响应体为
FAIL视为通知失败，系统将按策略重试。