---
url: >-
https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/onlinePayment/developer/APIUsage/index.md
description: 说明 PingPong Checkout API 的基础调用规则，包括 HTTPS、JSON 格式、字符集、金额格式、公共参数和响应规范。
---
# API 使用基本规则
## 基本信息
- 所有的API请求必须使用HTTPS。
- 请求时不应忽略服务器证书验证的错误，避免被恶意劫持。
## 数据格式
所有的API请求必须使用HTTPS。
PingPongCheckout支付API V4 使用 JSON 作为消息体的数据交换格式。请求须设置HTTP头部（图片上传API除外）：
```text:line-numbers title="📡 HTTP Headers"
Content-Type: application/json
Accept: application/json
```
::: note 提示
API应答中的数据有可能包含商户传入的数据，即可能是未经检查的用户输入内容。为了避免XSS（Cross-site scripting）攻击，请调用方在使用应答数据前根据场景做适当的转义或者过滤。
:::
## 参数兼容性
+ PingPongCheckout支付API V4 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
+ PingPongCheckout支付API V4 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
+ PingPongCheckout支付API V4 当请求或应答中的JSON键值对的值为空（null）时，可以省略
## 字符集
PingPongCheckout支付API V4 支持UTF-8字符集。
## 公共请求参数
> **参数必填属性说明:必填(M)，可选(O)，条件必填(C)。**
>
> **POST** | **JSON**
| 参数字段 | 参数类型 | 参数属性 | 参数说明 |
|:-----------|:------------|:-----|:-------------------------------------------------------------------------------------|
| accId | String(64) | M | PingPong 商户店铺编号 |
| clientId | String(64) | M | PingPong 商户号 |
| signType | String(32) | M | 签名规约，支持 MD5、SHA256，具体⻅本文签名规约一栏 |
| sign | String(128) | M | 签名，具体⻅本文签名规约一栏，所有参数均参与签名 |
| version | String(10) | M | 当前固定为1.0，后续随接口变动可能有调整 |
| bizContent | String | M | 请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 ，格式：JSON字符串 |
::: note 提示
- PingPongCheckout支付API V4 在请求时候，请求参数必须包含公共参数，业务参数需要在`bizContent`中传递。
- 请求时候必须携带`sign`参数，`accId`,`clientId`,`signType`,`version`，`bizContent`均参与签名
:::
## 公共响应参数
> **参数必填属性说明:必填(M)，可选(O)，条件必填(C)。**
>
> **POST** | **JSON**
| 参数字段 | 参数属性 | 参数说明 |
|:------------|:-------|:--------------------------------------------------------------------------------------|
| accId | M | PingPong 店铺号 |
| clientId | M | PingPong 商户号 |
| code | M | 状态码 |
| description | M | 描述 |
| signType | M | 签名规约，支持 MD5、SHA256，具体⻅本文签名规约 一栏 |
| sign | M | 签名，具体⻅本文签名规约一栏，所有参数均参与签名 |
| bizContent | String | 业务响应参数作为整体传入，长度不限 |
::: note 提示
- PingPongCheckout支付API V4 应答参数包含公共响应参数，业务参数在`bizContent`中传递。
:::
## 地区和国家格式
PingPongCheckout支付API V4 国家或地区的格式需要符合ISO 3166-1标准。请对照ISO 3166-1国家代码一栏。
美国和加拿大地区州代码请对照美国和加拿大州代码一栏。
## API状态码
请对照API状态码一栏。
## 金额格式 {#amount-format}
### 基本格式
金额传参为小数点格式，小数点后非0位数不能超过对应币种的小数位数，比如，USD币种最多为两位小数，正例：12.34，12.1，12.10，12，12.120000，12.0000，反例：12.121，12.0008，12.00100。
详见交易币种
需要注意的是币种对应的小数点位数当前使用的是JDK8自带的规则，某些国家币种的单位如果近年来有变化的话可能不适用，需自定义调整，在接入时也需注意。
### 交易合规要求
根据交易合规要求，**支付金额必须严格等于商品金额计算公式**：
```
amount = sum(unitPrice × number) + shippingFee + sum(unitTaxAmount × number) - sum(totalDiscountAmount)
```
| 字段 | 说明 |
|:-----|:-----|
| `unitPrice` | 商品单价 |
| `number` | 商品数量 |
| `shippingFee` | 运费（如有） |
| `unitTaxAmount` | 单个商品税费（如有） |
| `totalDiscountAmount` | 单个商品总优惠金额（如有） |
::: warning 注意
** Klarna 特殊规则**：使用 Klarna 支付时，商品总价必须等于支付金额（不包含运费等额外费用），即 `sum(goods.unitPrice × goods.number) = amount`。运费请单独添加 shipping-fee 商品项（name 和 description 都设置为 shipping-fee）。
详见Klarna-收银台或Klarna-S2S
:::
## 必传字段规则 {#required-fields}
根据商户业务类型不同，以下字段的必传要求有所区别：
| 字段 | 实物商户 | 游戏虚拟类 | 其他虚拟类 |
|:------------------|:------:|:--------------------------:|:--------------------------:|
| `shippingAddress` | **必填** | 可选 | 可选 |
| `billingAddress` | **必填** | 可选 | **必填** |
| `customer.email` | **必填** | 与 merchantUserId **必填其一** | 与 merchantUserId **必填其一** |
| `merchantUserId` | 可选 | 与 customer.email **必填其一** | 与 customer.email **必填其一** |
### 字段说明
- **shippingAddress**：送货地址信息
- **billingAddress**：账单地址信息
- **merchantUserId**：商户用户ID
- **email**：用户邮箱
### 商户类型说明
| 商户类型 | 说明 | 典型场景 |
|-------|---------------|-----------|
| 实物商户 | 销售实体商品，需要物流配送 | 电商平台、零售商 |
| 游戏虚拟类 | 游戏充值、虚拟道具等 | 游戏平台、应用内购 |
| 其他虚拟类 | 数字服务、订阅等 | SaaS、在线教育 |
::: tip 提示
- 以上必传规则仅在支付方式不要求传送的情况下适用。
- 若特定支付方式本身要求传送这些参数，则无论商户类型如何，都需要传送。
- 游戏虚拟类和其他虚拟类商户，`merchantUserId` 和 `customer.email` 至少需要填写一个，用于标识用户身份。
- 详情可以咨询技术支持
:::
## 签名规则
全报文字段参与签名（sign字段除外），字段根据ASCII码递增排序（字母升序排序）拼接，如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推
排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串
请求参数和同步返回参数，以及异步通知都为全报文签名
详见签名规约
## 0元支付
0元不允许支付，系统已限制，但0元绑卡可以