API 使用基本规则 | 开发指南
约 1753 字大约 6 分钟
2025-03-07
基本信息
- 所有的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)。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元绑卡可以
