---
url: 'https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/guide/APIUsage/index.md'
description: >-
  The basic rules for API usage introduce the usage specifications of
  PingPongCheckout payment API V4, suitable for developers who need to integrate
  payment functionality. All requests must be sent via HTTPS and use JSON
  format. Key features include: support for UTF-8 character set, good parameter
  compatibility, and inclusion of necessary public request and response
  parameters such as accId, clientId, etc., ensuring security and data integrity
---
# Basic Rules for API Usage

## Basic Information

- All API requests must use HTTPS.
- When making requests, do not ignore server certificate validation errors to avoid malicious hijacking.

## Data Format

All API requests must use HTTPS.
PingPongCheckout payment API V4 uses JSON as the data exchange format for message bodies. Requests must set HTTP headers (except for image upload APIs):

```text:line-numbers title="📡 HTTP Headers"
Content-Type: application/json
Accept: application/json
```

::: note Note
Data in API responses may contain data passed by merchants, which could be unchecked user input content. To prevent XSS (Cross-site scripting) attacks, please perform appropriate escaping or filtering on response data based on the scenario before using it.
:::

## Parameter Compatibility

+ PingPongCheckout payment API V4 new API versions may add new parameters or JSON key-value pairs in requests or responses
+ PingPongCheckout payment API V4 new API versions will not remove existing required parameters or JSON key-value pairs from requests and responses
+ PingPongCheckout payment API V4 when the value of a JSON key-value pair in requests or responses is empty (null), it can be omitted

## Character Set

PingPongCheckout payment API V4 supports UTF-8 character set.

## Public Request Parameters

<br/>
<el-tag type="danger" effect="dark">Parameter Required Attribute Description: Mandatory (M), Optional (O), Conditionally Mandatory (C).</el-tag>
<el-tag type="info" effect="dark">POST</el-tag>
<el-tag type="info" effect="dark">JSON</el-tag>
<br/>
<br/>

| Parameter Field | Parameter Type | Parameter Attribute | Parameter Description |
|:-----------|:------------|:-----|:---------------------|
| accId | String(64) | M | PingPong merchant store number |
| clientId | String(64) | M | PingPong merchant number |
| signType | String(32) | M | Signature specification, supports MD5, SHA256, see <a href='/en/notes/guide/sign/' target='_blank'>Signature Specification</a> section in this document |
| sign | String(128) | M | Signature, see <a href='/en/notes/guide/sign/' target='_blank'>Signature Specification</a> section in this document, all parameters participate in signature |
| version | String(10) | M | Currently fixed at 1.0, may be adjusted with subsequent interface changes |
| bizContent | String | M | Collection of request parameters, unlimited maximum length, all request parameters except public parameters must be passed in this parameter, format: JSON string |

::: note Note
- PingPongCheckout payment API V4 when making requests, request parameters must include public parameters, business parameters need to be passed in `bizContent`.
- When making requests, the `sign` parameter must be carried, `accId`, `clientId`, `signType`, `version`, `bizContent` all participate in signature
:::

## Public Response Parameters

<br/>
<el-tag type="danger" effect="dark">Parameter Required Attribute Description: Mandatory (M), Optional (O), Conditionally Mandatory (C).</el-tag>
<el-tag type="info" effect="dark">POST</el-tag>
<el-tag type="info" effect="dark">JSON</el-tag>
<br/>
<br/>

| Parameter Field | Parameter Attribute | Parameter Description |
|:------------|:-------|:----------------------|
| accId | M | PingPong store number |
| clientId | M | PingPong merchant number |
| code | M | Status code |
| description | M | Description |
| signType | M | Signature specification, supports MD5, SHA256, see <a href='/en/notes/guide/sign/' target='_blank'>Signature Specification</a> section in this document |
| sign | M | Signature, see <a href='/en/notes/guide/sign/' target='_blank'>Signature Specification</a> section in this document, all parameters participate in signature |
| bizContent | String | Business response parameters passed as a whole, unlimited length |

::: note Note
- PingPongCheckout payment API V4 response parameters include public response parameters, business parameters are passed in `bizContent`.
:::

## Region and Country Format

PingPongCheckout payment API V4 country or region formats must comply with ISO 3166-1 standard. Please refer to <a href='/en/notes/appendix/countryCode/' target='_blank'>ISO 3166-1 Country Codes</a> section.

For US and Canada state codes, please refer to <a href='/en/notes/appendix/stateCode/' target='_blank'>US and Canada State Codes</a> section.

## API Status Codes

Please refer to <a href='/en/notes/appendix/successCodeList/' target='_blank'>API Status Codes</a> section.

## Amount Format

Amount parameters use decimal format, the non-zero digits after the decimal point cannot exceed the decimal places of the corresponding currency. For example, USD currency has a maximum of two decimal places. Examples: 12.34, 12.1, 12.10, 12, 12.120000, 12.0000; Counter examples: 12.121, 12.0008, 12.00100.
See details in <a href='/en/notes/appendix/transactionCurrency/' target='_blank'>Transaction Currency</a>
Note that the current decimal places for currencies follow JDK8's built-in rules. For currencies of certain countries where units have changed in recent years, custom adjustments may be needed, which should be noted during integration.

## Signature Rules
All message fields participate in signature (except the sign field). Fields are concatenated according to ASCII code ascending order (alphabetical ascending order). If encountering identical characters, sort by the second character's key-value ASCII code ascending order, and so on.
After sorting, parameters and their corresponding values are combined into the format Parameter=ParameterValue, and these parameters are connected with & characters. The resulting string is the string to be signed.
Request parameters, synchronous return parameters, and asynchronous notifications all use full-message signatures.
See details in <a href='/en/notes/guide/sign/' target='_blank'>Signature Specification</a>

## Zero Amount Payment

Zero amount payments are not allowed and are restricted by the system, but zero amount card binding is permitted.