Basic Rules for API Usage
About 890 wordsAbout 3 min
2025-03-07
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):
Content-Type: application/json
Accept: application/jsonNote
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
Parameter Required Attribute Description: Mandatory (M), Optional (O), Conditionally Mandatory (C).POSTJSON
| 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 Signature Specification section in this document |
| sign | String(128) | M | Signature, see Signature Specification 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
- 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
signparameter must be carried,accId,clientId,signType,version,bizContentall participate in signature
Public Response Parameters
Parameter Required Attribute Description: Mandatory (M), Optional (O), Conditionally Mandatory (C).POSTJSON
| 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 Signature Specification section in this document |
| sign | M | Signature, see Signature Specification section in this document, all parameters participate in signature |
| bizContent | String | Business response parameters passed as a whole, unlimited length |
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 ISO 3166-1 Country Codes section.
For US and Canada state codes, please refer to US and Canada State Codes section.
API Status Codes
Please refer to API Status Codes 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 Transaction Currency 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 Signature Specification
Zero Amount Payment
Zero amount payments are not allowed and are restricted by the system, but zero amount card binding is permitted.
