Invoice Reconciliation
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 first.
Document Rhythm (Customer View)
During the subscription lifecycle, document-related events reach the merchant in the following rhythm:
| 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
The 4 Webhook Events
| Event | Trigger | Payload reference |
|---|---|---|
INVOICE_CREATED | Invoice created (DRAFT status) | Invoice Created Notification (not produced in instant-charge subscription scenarios) |
INVOICE_FINALIZED | Invoice finalized, document number assigned | Invoice Finalized Notification |
CUSTOMER_UPDATED | Customer profile updated | Customer Updated Notification |
RECEIPT_CREATED | Forward payment succeeded, receipt generated | Receipt Created Notification |
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) |
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
- Charge succeeded: receive the payment notification (contains
invoiceId); - Invoice finalized: receive the
INVOICE_FINALIZEDevent (containsinvoiceId+invoiceNumber); - Receipt generated: receive the
RECEIPT_CREATEDevent (containsreceiptId+receiptNumber); - When you need the invoice: call Invoice Download for the PDF link to send to the customer, or call Invoice Details to verify amount and status;
- When you need the receipt: call Receipt Download 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.
