POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

• requestIdString(64)Required

  Unique request ID, globally unique.
• invoiceIdString(64)Required

  Invoice ID.

Request Body Example

{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "4.0",
  "bizContent": {
    "requestId": "req_20260507_0011",
    "invoiceId": "INV-260507100000000001"
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

• subscriptionDetailObjectOptional

  Subscription information object. Not returned for non-subscription scenarios.

  • subscriptionIdString(64)Optional

    PingPong subscription ID.
  • partnerSubscriptionIdString(64)Optional

    Merchant-side subscription ID.
  • startAtString(10)Optional

    Start of the billing period covered by this invoice, as a 10-digit second-level timestamp string.
  • endAtString(10)Optional

    End of the billing period covered by this invoice, as a 10-digit second-level timestamp string.
• customerObjectOptional

  Customer object, same structure as the customer API response body.

  • customerIdString(64)Required

    PingPong customer ID.
  • partnerCustomerIdString(64)Required

    Merchant-side customer identifier, i.e. the user's member ID on the merchant's website. Unique within the same store.
  • firstNameString(64)Optional

    First name.
  • lastNameString(64)Optional

    Last name.
  • companyNameString(128)Optional

    Company name.
  • emailString(128)Optional

    Email address.
  • phoneString(20)Optional

    Phone number.
  • addressObjectOptional

    Address object, same structure as the request address.

    • countryString(2)Optional

      Two-letter country code, ISO 3166.
    • stateString(128)Optional

      State or province.
    • cityString(50)Optional

      City.
    • postalCodeString(16)Optional

      Postal code.
    • line1String(256)Optional

      Address line 1.
    • line2String(256)Optional

      Address line 2.
  • languageString(12)Optional

    Preferred language and locale.
  • metadataString(512)Optional

    Merchant-defined custom string.
  • createdAtString(10)Required

    Creation time as a 10-digit second-level timestamp string.
  • updatedAtString(10)Required

    Last update time as a 10-digit second-level timestamp string.
• merchantObjectOptional

  Issuer (merchant) object.

  • legalNameString(128)Optional

    Merchant legal name.
  • addressObjectOptional

    Merchant address object.

    • businessAddressEnString(256)Optional

      Merchant business address in English.
    • postCodeString(16)Optional

      Postal code.
    • countryString(64)Optional

      Country. Sandbox responses return the full country name (e.g. China).
  • websiteString(255)Optional

    Merchant website.
• paymentObjectOptional

  Payment information object.

  • statusString(32)Optional

    Payment status.
  • transactionIdString(64)Optional

    PingPong transaction ID.
  • merchantTransactionIdString(64)Optional

    Merchant transaction ID.
  • methodTypeString(32)Optional

    Payment method: the card brand for card payments (e.g. VISA), or an upper-case APM name (such as PAYNOW).
  • transactionTimeString(32)Optional

    Payment completion time, ISO 8601 UTC.
• downloadObjectOptional

  File download object. Can also use the Invoice Download API to obtain the download URL.

  • urlString(512)Optional

    Download URL, valid for 30 days.
  • expiresAtString(10)Optional

    URL expiration time as a 10-digit second-level timestamp string.
  • versionIntegerOptional

    Invoice version that the file corresponds to.
  • formatString(16)Optional

    File format, currently PDF.
• requestIdString(64)Required

  Unique request ID, echoed from the request.
• invoiceIdString(64)Required

  Invoice ID.
• invoiceNumberString(64)Conditional

  Invoice number, assigned after finalization.
• versionIntegerRequired

  Invoice version number, incremented on every re-render.
• statusString(32)Required

  Invoice status:

  • DRAFT: draft, not finalized after creation; can be updated or voided.
  • FINALIZED: finalized, invoice number assigned, downloadable.
  • VOID: voided.

  Observed in sandbox: the invoice status follows the payment pipeline and may also be PAYMENT_PENDING (charge in progress) / PAID / PARTIALLY_REFUNDED (refunds attach to the first invoice) / FULLY_REFUNDED.
• createdAtString(10)Required

  Creation time as a 10-digit second-level timestamp string.
• finalizedAtString(10)Optional

  Finalization time as a 10-digit second-level timestamp string.
• paidAtString(10)Optional

  Payment completion time as a 10-digit second-level timestamp string.
• currencyString(3)Required

  Currency, ISO 4217.
• subtotalString(12)Required

  Subtotal amount as a decimal string.
• totalString(12)Required

  Total amount as a decimal string.
• amountPaidString(12)Optional

  Amount already paid, as a decimal string. Sandbox verified (2026-10-19): not returned while the invoice is unpaid (PAYMENT_PENDING).

Request Body Example

{
  "clientId": "20250101123456",
  "accId": "ACC001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "code": "000000",
  "description": "SUCCESS",
  "bizContent": {
    "requestId": "req_20260507_0011",
    "invoiceId": "INV-260507100000000001",
    "invoiceNumber": "INV-2605070001",
    "version": 1,
    "status": "FINALIZED",
    "createdAt": "2026-05-07T00:00:00Z",
    "finalizedAt": "2026-05-07T00:01:00Z",
    "paidAt": "2026-05-07T00:02:00Z",
    "currency": "USD",
    "subtotal": "10.00",
    "total": "10.00",
    "amountPaid": "10.00",
    "subscriptionDetail": {
      "subscriptionId": "SUB-2605070001",
      "partnerSubscriptionId": "sub_20260507_0002",
      "startAt": "2026-05-07T00:00:00Z",
      "endAt": "2026-06-07T00:00:00Z"
    },
    "customer": {
      "customerId": "CUS-260507100000000001",
      "partnerCustomerId": "USER_001",
      "firstName": "James",
      "lastName": "LeBron",
      "email": "james@example.com"
    },
    "merchant": {
      "legalName": "Example Pte. Ltd.",
      "address": {
        "businessAddressEn": "10 Marina Boulevard, Singapore",
        "postCode": "018983",
        "country": "SG"
      },
      "website": "https://merchant.example.com"
    },
    "payment": {
      "status": "SUCCESS",
      "transactionId": "260507100000000001",
      "merchantTransactionId": "M202605070001",
      "methodType": "CARD",
      "transactionTime": "2026-05-07T00:02:00Z"
    },
    "download": {
      "url": "https://example.com/invoice/INV-2605070001.pdf",
      "expiresAt": "2026-06-06T00:00:00Z",
      "version": 1,
      "format": "PDF"
    }
  }
}

Previous pageQuery Customer

Next pageInvoice Download