Invoice Overview
The Invoice V4 API provides Customer, Invoice and Receipt management capabilities, together with webhook notifications for invoice and customer events. It applies to subscription billing, invoice issuance and payment receipt archiving scenarios.
API List
Customer APIs
| API | Path | Description |
|---|---|---|
| Create Customer | POST /v4/customers/create | Creates a customer from the merchant-side identifier and returns the PingPong customer ID |
| Update Customer | POST /v4/customers/update | Updates a customer profile by PingPong customer ID; only submitted fields are changed |
| Query Customer | POST /v4/customers/query | Queries a customer profile by PingPong customer ID |
Invoice APIs
| API | Path | Description |
|---|---|---|
| Invoice Details | POST /v4/invoices/query | Queries invoice details by invoice ID, including amount, customer, merchant snapshot, payment information and download link |
| Invoice Download | POST /v4/invoices/download | Generates and returns the invoice PDF download link |
| Receipt Details | POST /v4/invoices/receipt/query | Queries payment receipt details by receipt ID, including payment and refund records |
| Receipt Download | POST /v4/invoices/receipt/download | Generates and returns the receipt PDF download link |
Webhook Notifications
| Event | Trigger | Payload |
|---|---|---|
INVOICE_CREATED | Invoice created (DRAFT status) | Invoice Created Notification |
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 |
Common Conventions
- Amounts: decimal strings (e.g.
12.34). - Timestamps: 10-digit second-level timestamp strings (e.g.
1792473374).
Common Request Parameters
Every API carries the following common top-level parameters:
| Field | Required | Description |
|---|---|---|
| clientId | Required | Merchant ID |
| accId | Required | Store ID |
| signType | Required | Signature type, MD5 |
| sign | Required | Signature value, following the V4 signing rules(Open in new window) |
| version | Required | API version, fixed at 4.0 |
| bizContent | Required | Business parameters as a JSON string (see each API's bizContent parameters) |
Common Response Parameters
| Field | Description |
|---|---|
| clientId | Merchant ID |
| accId | Store ID |
| signType | Signature type |
| sign | Signature value |
| code | Response code: 000000 on success; business error codes on failure (102000 parameter error / 500003 resource not found / 910001 business validation failure / 910005 operation not supported in current status / 910008 in-flight change task exists / 500000 system error, etc.) |
| description | Response description |
| bizContent | Business response as a JSON string (see each API's bizContent response) |
Note
The API version of this module is fixed at 4.0 (unlike the 1.0 of payment APIs on this site), and response times are in ISO 8601 UTC format (payment/subscription APIs use timestamps). Please distinguish them during integration.
Webhook General Notes
- Merchants configure callback addresses per event; only one callback URL per event per merchant is supported. Unconfigured events are not pushed.
- Unified envelope (identical across all events):
clientId,accId,signType,bizContent,sign. - The first field inside
bizContent,notifyType, identifies the event type; business fields are camelCase and time fields are second-level timestamp numbers. - Return HTTP 2xx when processing succeeds; a non-2xx status or a
FAILresponse body is treated as a notification failure and the system retries according to its policy.