API 使用基本规则
基本信息
- 所有的API请求必须使用HTTPS。
- 请求时不应忽略服务器证书验证的错误，避免被恶意劫持。
数据格式
所有的API请求必须使用HTTPS。 PingPongCheckout支付API V4 使用 JSON 作为消息体的数据交换格式。请求须设置HTTP头部（图片上传API除外）：
Content-Type: application/json
Accept: application/json提示
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字符串 |
提示
- 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 | 业务响应参数作为整体传入，长度不限 |
提示
- PingPongCheckout支付API V4 应答参数包含公共响应参数，业务参数在
bizContent中传递。
地区和国家格式
PingPongCheckout支付API V4 国家或地区的格式需要符合ISO 3166-1标准。请对照ISO 3166-1国家代码一栏。
美国和加拿大地区州代码请对照美国和加拿大州代码一栏。
API状态码
请对照API状态码一栏。
金额格式
基本格式
金额传参为小数点格式，小数点后非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 | 单个商品总优惠金额（如有） |
注意
** Klarna 特殊规则**：使用 Klarna 支付时，商品总价必须等于支付金额（不包含运费等额外费用），即 sum(goods.unitPrice × goods.number) = amount。运费请单独添加 shipping-fee 商品项（name 和 description 都设置为 shipping-fee）。 详见Klarna-收银台或Klarna-S2S
必传字段规则
根据商户业务类型不同，以下字段的必传要求有所区别：
| 字段 | 实物商户 | 游戏虚拟类 | 其他虚拟类 |
|---|---|---|---|
shippingAddress | 必填 | 可选 | 可选 |
billingAddress | 必填 | 可选 | 必填 |
customer.email | 必填 | 与 merchantUserId 必填其一 | 与 merchantUserId 必填其一 |
merchantUserId | 可选 | 与 customer.email 必填其一 | 与 customer.email 必填其一 |
字段说明
- shippingAddress：送货地址信息
- billingAddress：账单地址信息
- merchantUserId：商户用户ID
- email：用户邮箱
商户类型说明
| 商户类型 | 说明 | 典型场景 |
|---|---|---|
| 实物商户 | 销售实体商品，需要物流配送 | 电商平台、零售商 |
| 游戏虚拟类 | 游戏充值、虚拟道具等 | 游戏平台、应用内购 |
| 其他虚拟类 | 数字服务、订阅等 | SaaS、在线教育 |
提示
- 以上必传规则仅在支付方式不要求传送的情况下适用。
- 若特定支付方式本身要求传送这些参数，则无论商户类型如何，都需要传送。
- 游戏虚拟类和其他虚拟类商户，
merchantUserId和customer.email至少需要填写一个，用于标识用户身份。 - 详情可以咨询技术支持
签名规则
全报文字段参与签名（sign字段除外），字段根据ASCII码递增排序（字母升序排序）拼接，如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推 排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串 请求参数和同步返回参数，以及异步通知都为全报文签名 详见签名规约
0元支付
0元不允许支付，系统已限制，但0元绑卡可以