Invoice 对账
本页说明订阅场景下 Invoice 票据和 Receipt 凭证的对账方案。接入主流程请先阅读 Subscription 集成方案。
票据节奏(客户视角)
订阅生命周期中,票据类事件按以下节奏到达商户:
| 时点 | 商户收到 | 用途 |
|---|---|---|
| 首期支付成功 | INVOICE_FINALIZED + RECEIPT_CREATED + 支付通知 | 开通服务、给客户提供票据 |
| 续费前约 1 小时 | INVOICE_CREATED(DRAFT) | 提前向客户预告下期账单 |
| 续费扣款时 | INVOICE_FINALIZED | 账单定稿 |
| 续费扣款成功 | RECEIPT_CREATED + 支付通知 | 入账、对账、出收据 |
| 取消时 | DRAFT→VOID + SUBSCRIPTION_CANCELLED | 未执行账单作废 |
注意:实时扣款成功场景不产生 INVOICE_CREATED(票据创建即定稿),需要票据号的场景以 INVOICE_FINALIZED 为准。
关键 ID 获取路径
| ID | 来源 | 用途 |
|---|---|---|
invoiceId | 支付通知(paymentNotifyUrl)或 INVOICE_FINALIZED 事件 | 票据查询/下载 |
receiptId | RECEIPT_CREATED 事件(商户后台配置回调) | 凭证查询/下载 |
invoiceNumber | INVOICE_FINALIZED 事件或票据查询响应 | 客户可见的单据号 |
票据状态机
4 个 Webhook 事件
| 事件 | 触发时机 | 报文说明 |
|---|---|---|
INVOICE_CREATED | 票据创建完成(DRAFT 状态) | 票据创建通知(订阅实时扣款场景不产生) |
INVOICE_FINALIZED | 票据定稿,单据号分配完成 | 票据定稿通知 |
CUSTOMER_UPDATED | 买家资料更新成功 | 买家更新通知 |
RECEIPT_CREATED | 正向支付成功,支付凭证生成 | 凭证创建通知 |
回调配置
这 4 个事件不走请求里的 notifyUrl。V4 版本需联系 PingPong 技术支持按事件配置回调地址(同一商户同一事件仅支持一个回调 URL)。接入时务必先完成事件订阅配置,否则收不到通知。
4 个查询/下载接口
| 接口 | 路径 | 说明 |
|---|---|---|
| 票据详情 | POST /v4/invoices/query | 按 invoiceId 查询金额、状态、客户、商户快照、支付信息、下载链接 |
| 票据下载 | POST /v4/invoices/download | 生成并返回票据 PDF 下载链接(30 天有效) |
| 凭证详情 | POST /v4/invoices/receipt/query | 按 receiptId 查询支付状态、金额、退款记录 |
| 凭证下载 | POST /v4/invoices/receipt/download | 生成并返回凭证 PDF 下载链接(30 天有效) |
OSS 下载链接特性
download 接口返回的 OSS 签名 URL 仅支持 GET 请求下载;HEAD 请求会返回 403(属正常行为,签名未包含 HEAD 方法)。请使用 GET 下载文件。
典型对账流程
- 扣款成功:接收支付通知(含
invoiceId); - 票据定稿:接收
INVOICE_FINALIZED事件(含invoiceId+invoiceNumber); - 凭证生成:接收
RECEIPT_CREATED事件(含receiptId+receiptNumber); - 商户需要票据时:调 票据下载 拿 PDF 链接发给客户,或调 票据详情 核对金额和状态;
- 商户需要凭证时:调 凭证下载 拿 PDF 链接。
常见问题
Q:Update 补扣的 invoice 在哪? A:Update 产生的补扣也会生成独立 invoice(invoiceId 不同),可从支付通知或 INVOICE_FINALIZED 事件中获取。
Q:退款后票据状态怎么变? A:退款挂在首期 invoice 上,状态从 PAID 变为 PARTIALLY_REFUNDED(部分退款)或 FULLY_REFUNDED(全额退款)。
Q:INVOICE_CREATED 什么时候会收到? A:仅当票据先创建为 DRAFT、后续再定稿的场景(如续费前 1 小时出账)。首期实时扣款场景不产生该事件。
