基本信息

• 所有的API请求必须使用HTTPS。
• 请求时不应忽略服务器证书验证的错误，避免被恶意劫持。

数据格式

所有的API请求必须使用HTTPS。 PingPongCheckout支付API V4 使用 JSON 作为消息体的数据交换格式。请求须设置HTTP头部（图片上传API除外）：

📡 HTTP Headers

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)。POSTJSON

参数字段	参数类型	参数属性	参数说明
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)。POSTJSON

参数字段	参数属性	参数说明
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元绑卡可以

下一页API 端点地址