---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/invoice/overview/index.md
description: >-
  The Invoice V4 API provides Customer, Invoice and Receipt management
  capabilities, together with webhook notifications for invoice and customer
  events.
---
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](/en/notes/notify/invoice/created/) |
| `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/) |

## 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](/en/notes/onlinePayment/developer/sign/) |
| 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) |

::: warning 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 `FAIL` response body is treated as a notification failure and the system retries according to its policy.