--- title: Invoice 对账 permalink: /notes/zh/integrate/subscription/invoice-reconciliation/ createTime: '2026/10/20 14:00:00' nosearch: true llm: exclude: true description: '说明订阅场景下 Invoice 票据和 Receipt 凭证的生成节奏、查询方式、下载方式和 Webhook 事件,帮助商户完成对账闭环。' --- 本页说明订阅场景下 Invoice 票据和 Receipt 凭证的对账方案。接入主流程请先阅读 [Subscription 集成方案](/notes/zh/integrate/subscription/integration/)。 ## 票据节奏(客户视角) 订阅生命周期中,票据类事件按以下节奏到达商户: ```mermaid sequenceDiagram participant M as 商户系统 participant PP as PingPong Note over PP: 订阅创建(首期,实时扣款) M->>PP: subscriptions/create PP-->>M: INVOICE_FINALIZED(票据号,创建即定稿) PP-->>M: RECEIPT_CREATED(收据号) PP-->>M: 支付通知 + SUBSCRIPTION_ACTIVATED Note over PP: 每个续费周期 PP-->>M: INVOICE_CREATED(提前约 1 小时出账, DRAFT) PP-->>M: INVOICE_FINALIZED(扣款时定稿) PP-->>M: RECEIPT_CREATED + 支付通知(扣款成功) Note over PP: 取消订阅 M->>PP: subscriptions/cancel PP-->>M: 未执行的 DRAFT 票据 → VOID PP-->>M: SUBSCRIPTION_CANCELLED ``` | 时点 | 商户收到 | 用途 | |:---|:---|:---| | 首期支付成功 | `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` 事件或票据查询响应 | 客户可见的单据号 | ## 票据状态机 ```mermaid stateDiagram-v2 [*] --> DRAFT: 创建 DRAFT --> FINALIZED: finalize DRAFT --> VOID: 订阅取消 FINALIZED --> PAYMENT_PENDING: 扣款处理中 FINALIZED --> PAYMENT_FAILED: 扣款失败 FINALIZED --> PAID: 扣款成功 PAID --> PARTIALLY_REFUNDED: 部分退款 PAID --> FULLY_REFUNDED: 全额退款 PARTIALLY_REFUNDED --> FULLY_REFUNDED: 继续退款至全退 ``` ## 4 个 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/) | ::: warning 回调配置 这 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 天有效) | ::: tip OSS 下载链接特性 download 接口返回的 OSS 签名 URL **仅支持 GET 请求下载**;HEAD 请求会返回 403(属正常行为,签名未包含 HEAD 方法)。请使用 GET 下载文件。 ::: ## 典型对账流程 1. **扣款成功**:接收支付通知(含 `invoiceId`); 2. **票据定稿**:接收 `INVOICE_FINALIZED` 事件(含 `invoiceId` + `invoiceNumber`); 3. **凭证生成**:接收 `RECEIPT_CREATED` 事件(含 `receiptId` + `receiptNumber`); 4. **商户需要票据时**:调 [票据下载](/notes/zh/subscription/invoice/download/) 拿 PDF 链接发给客户,或调 [票据详情](/notes/zh/subscription/invoice/query/) 核对金额和状态; 5. **商户需要凭证时**:调 [凭证下载](/notes/zh/subscription/invoice/receiptDownload/) 拿 PDF 链接。 ## 常见问题 **Q:Update 补扣的 invoice 在哪?** A:Update 产生的补扣也会生成独立 invoice(`invoiceId` 不同),可从支付通知或 `INVOICE_FINALIZED` 事件中获取。 **Q:退款后票据状态怎么变?** A:退款挂在首期 invoice 上,状态从 `PAID` 变为 `PARTIALLY_REFUNDED`(部分退款)或 `FULLY_REFUNDED`(全额退款)。 **Q:`INVOICE_CREATED` 什么时候会收到?** A:仅当票据先创建为 DRAFT、后续再定稿的场景(如续费前 1 小时出账)。首期实时扣款场景不产生该事件。