--- title: Invoice Reconciliation permalink: /en/notes/integrate/subscription/invoice-reconciliation/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Explains the generation rhythm, query and download methods, and webhook events for Invoice documents and Receipt vouchers in subscription scenarios, helping merchants close the reconciliation loop.' --- This page explains the reconciliation approach for Invoice documents and Receipt vouchers in subscription scenarios. For the main integration flow, read the [Subscription Integration Guide](/en/notes/integrate/subscription/integration/) first. ## Document Rhythm (Customer View) During the subscription lifecycle, document-related events reach the merchant in the following rhythm: ```mermaid sequenceDiagram participant M as Merchant system participant PP as PingPong Note over PP: Subscription created (first period, instant charge) M->>PP: subscriptions/create PP-->>M: INVOICE_FINALIZED (invoice number; finalized at creation) PP-->>M: RECEIPT_CREATED (receipt number) PP-->>M: Payment notification + SUBSCRIPTION_ACTIVATED Note over PP: Every renewal period PP-->>M: INVOICE_CREATED (billed ~1 hour ahead, DRAFT) PP-->>M: INVOICE_FINALIZED (finalized at charge time) PP-->>M: RECEIPT_CREATED + payment notification (charge succeeded) Note over PP: Cancellation M->>PP: subscriptions/cancel PP-->>M: Unexecuted DRAFT invoices → VOID PP-->>M: SUBSCRIPTION_CANCELLED ``` | Moment | Merchant receives | Purpose | |:---|:---|:---| | First payment succeeded | `INVOICE_FINALIZED` + `RECEIPT_CREATED` + payment notification | Activate service, provide documents to the customer | | ~1 hour before renewal | `INVOICE_CREATED` (DRAFT) | Pre-notify the customer of the upcoming bill | | At renewal charge | `INVOICE_FINALIZED` | Bill finalized | | Renewal charge succeeded | `RECEIPT_CREATED` + payment notification | Booking, reconciliation, issuing receipts | | On cancellation | DRAFT→VOID + `SUBSCRIPTION_CANCELLED` | Unexecuted bills voided | **Note**: in instant-charge scenarios **`INVOICE_CREATED` is not produced** (the invoice is finalized at creation). If you need the invoice number, rely on `INVOICE_FINALIZED`. ## How to Obtain Key IDs | ID | Source | Purpose | |:---|:---|:---| | `invoiceId` | Payment notification (`paymentNotifyUrl`) or the `INVOICE_FINALIZED` event | Invoice query/download | | `receiptId` | `RECEIPT_CREATED` event (callback configured in the merchant portal) | Receipt query/download | | `invoiceNumber` | `INVOICE_FINALIZED` event or the Invoice Details response | Customer-facing document number | ## Invoice State Machine ```mermaid stateDiagram-v2 [*] --> DRAFT: created DRAFT --> FINALIZED: finalize DRAFT --> VOID: subscription cancelled FINALIZED --> PAYMENT_PENDING: charge in progress FINALIZED --> PAYMENT_FAILED: charge failed FINALIZED --> PAID: charge succeeded PAID --> PARTIALLY_REFUNDED: partial refund PAID --> FULLY_REFUNDED: full refund PARTIALLY_REFUNDED --> FULLY_REFUNDED: further refunds until fully refunded ``` ## The 4 Webhook Events | Event | Trigger | Payload reference | |:---|:---|:---| | `INVOICE_CREATED` | Invoice created (DRAFT status) | [Invoice Created Notification](/en/notes/notify/invoice/created/) (not produced in instant-charge subscription scenarios) | | `INVOICE_FINALIZED` | Invoice finalized, document number assigned | [Invoice Finalized Notification](/en/notes/notify/invoice/finalized/) | | `CUSTOMER_UPDATED` | Customer profile updated | [Customer Updated Notification](/en/notes/notify/invoice/customerUpdated/) | | `RECEIPT_CREATED` | Forward payment succeeded, receipt generated | [Receipt Created Notification](/en/notes/notify/invoice/receiptCreated/) | ::: warning Callback configuration These 4 events **do not use the `notifyUrl` from API requests**. For V4, callback addresses are configured per event by **contacting PingPong technical support** (only one callback URL per event per merchant). Make sure the event subscription configuration is completed during integration, otherwise you will not receive notifications. ::: ## The 4 Query/Download APIs | API | Path | Description | |:---|:---|:---| | Invoice Details | `POST /v4/invoices/query` | Query amount, status, customer, merchant snapshot, payment information and download link by `invoiceId` | | Invoice Download | `POST /v4/invoices/download` | Generate and return the invoice PDF download link (valid for 30 days) | | Receipt Details | `POST /v4/invoices/receipt/query` | Query payment status, amount and refund records by `receiptId` | | Receipt Download | `POST /v4/invoices/receipt/download` | Generate and return the receipt PDF download link (valid for 30 days) | ::: tip OSS download link behavior The OSS signed URL returned by the download APIs **only supports GET downloads**; HEAD requests return 403 (expected behavior — the signature does not include the HEAD method). Use GET to download the file. ::: ## Typical Reconciliation Flow 1. **Charge succeeded**: receive the payment notification (contains `invoiceId`); 2. **Invoice finalized**: receive the `INVOICE_FINALIZED` event (contains `invoiceId` + `invoiceNumber`); 3. **Receipt generated**: receive the `RECEIPT_CREATED` event (contains `receiptId` + `receiptNumber`); 4. **When you need the invoice**: call [Invoice Download](/en/notes/subscription/invoice/download/) for the PDF link to send to the customer, or call [Invoice Details](/en/notes/subscription/invoice/query/) to verify amount and status; 5. **When you need the receipt**: call [Receipt Download](/en/notes/subscription/invoice/receiptDownload/) for the PDF link. ## FAQ **Q: Where is the invoice for an Update surcharge?** A: Surcharges produced by Update also generate their own invoice (with a different `invoiceId`), available from the payment notification or the `INVOICE_FINALIZED` event. **Q: How does the invoice status change after a refund?** A: Refunds are attached to the first-period invoice, whose status changes from `PAID` to `PARTIALLY_REFUNDED` (partial refund) or `FULLY_REFUNDED` (full refund). **Q: When will I receive `INVOICE_CREATED`?** A: Only in scenarios where an invoice is first created as DRAFT and finalized later (e.g. billed ~1 hour before renewal). Instant-charge first-payment scenarios do not produce this event.