PingPong Element SDK 集成指南
约 2155 字大约 7 分钟
2025-01-05
SDK集成流程
架构设计
核心模块
| 模块 | 职责 |
|---|---|
| PingPongSDK | SDK 唯一入口,暴露 init / createElement 方法 |
| PingPongElement | 所有支付按钮的基类,提供 .on() / .off() 事件机制 |
支付模式
SDK 支持两种主要模式:
- Payment: 下单并支付模式,适用于标准支付流程
- Vault: PayPal 独立签约模式,用于绑定钱包
接入流程
1. 获取 sdkAccessToken
商户后端系统通过调用获取 sdkAccessToken 接口得到访问凭证。
支付场景:
- 调用
/v4/session/init接口获取 sdkAccessToken
签约场景:
- POST 调用已有签约接口获取 sdkAccessToken 和 JS URL
2. 引入 Element SDK
根据您的业务环境,选择相应的 SDK 版本进行引入:
<script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/sandbox/v1/index.js"></script><script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/production/v1/index.js"></script><script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/production-sg/v1/index.js"></script>3. 初始化 SDK
入参说明
modeRequiredstring
业务模式
Payment(支付) 或 Vault(PayPal 独立签约)
envRequiredstring
运行环境
sandbox(沙箱) 或 production(生产)
amountRequiredstring
交易金额
用于收银台展示
currencyRequiredstring
交易币种
countryRequiredstring
国家/地区代码
如 US、CN、UK 等
accIdRequiredstring
商户账户 ID
localeRequiredstring
界面语言
en、zh-CN 等
regionOptionalstring
fra
地区
sg 或 fra
sdkAccessTokenRequiredstring
SDK 访问凭证
merchantResultUrlRequiredstring
支付完成后的跳转地址
createOrderOptionalFunction
下单函数
mode 为 Payment 时必传。该函数接收一个包含 payMethod 的对象参数,表示用户选择的支付方式
goodsRequiredArray<GoodsItem>
商品信息数组
详见下方 goods 数组结构
biztypeOptionalstring
业务类型
可选值: CodeGrant
recurringInfoDTOOptionalObject
Recurring 配置，ApplePay 签约必传
初始化示例
await PingPongSDK.init({
mode: 'Payment', // 业务模式: Payment 或 Vault
env: 'sandbox', // 运行环境
amount: '19.99', // 交易金额
currency: 'USD', // 交易币种
country: 'US', // 国家/地区代码
accId: 'ACC_123', // 商户账户ID
locale: 'en', // 语言设置
region: 'fra', // 地区: sg 或 fra
sdkAccessToken: 'your_sdk_token', // SDK访问令牌
merchantResultUrl: 'https://merchant-result.com', // 支付完成跳转地址
// mode 为 Payment 时必传
createOrder: async ({payMethod}) => {
console.log('用户选择的支付方式:', payMethod);
// 调用商户后端下单接口
const response = await fetch('/xx/xx', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
payMethod, // 传递支付方式到后端
xx: 'xx'
})
});
const result = await response.json();
return result.token; // 返回订单 token
},
// 商品信息数组（必填）
goods: [
{
name: '商品名称',
description: '商品描述',
imgUrl: 'https://example.com/product.jpg',
sku: 'SKU123',
unitPrice: '19.99',
number: '2',
virtualProduct: 'N'
}
],
// ApplePay 签约时必传
recurringInfoDTO: {
recurringPaymentStartDate: '2024-06-01 00:00:00',
recurringPaymentIntervalUnit: 'month',
recurringPaymentIntervalCount: '6',
recurringPaymentEndDate: '2024-12-01 00:00:00'
}
});goods 数组结构
商品信息数组包含每个商品的详细信息。
nameRequiredstring
商品名称
descriptionOptionalstring
商品描述
imgUrlOptionalstring
商品图片 URL
skuOptionalstring
商品 SKU
unitPriceRequiredstring
商品单价
numberRequiredstring
商品数量
virtualProductOptionalstring
是否为虚拟产品
Y 或 N
示例:
goods: [
{
name: '无线蓝牙耳机',
description: '高品质音质，30小时续航',
imgUrl: 'https://cdn.example.com/product1.jpg',
sku: 'HEADPHONE-BT-001',
unitPrice: '99.99',
number: '1',
virtualProduct: 'N'
},
{
name: '音乐会员月卡',
description: '畅听千万首正版音乐',
imgUrl: 'https://cdn.example.com/product2.jpg',
sku: 'VIP-MUSIC-1M',
unitPrice: '15.00',
number: '1',
virtualProduct: 'Y'
}
]4. 创建支付元素
4.1 Apple Pay 按钮
const applePay = await PingPongSDK.createElement('applePayButton', {
buttonType: 'buy', // 按钮类型: buy | plain
buttonColor: 'black', // 按钮颜色: black | white | white-outline
style: {
width: '100%',
height: '40px',
borderRadius: '4px'
},
payDiscount: { // 营销活动配置(可选)
activityNo: 'EEE',
costAmount: '19.99', // 原始金额
discountAmount: '2.00' // 折扣金额
}
});4.2 Google Pay 按钮
const googlePay = await PingPongSDK.createElement('googlePayButton', {
buttonType: 'buy', // 按钮类型: buy | subscribe
buttonColor: 'black', // 按钮颜色: black | white
style: {
width: '100%',
height: '40px',
borderRadius: '4px'
},
payDiscount: {
activityNo: 'EEE',
costAmount: '19.99',
discountAmount: '2.00'
}
});4.3 PayPal 按钮
const paypal = await PingPongSDK.createElement('paypalButton', {
buttonType: 'buttons', // buttons | marks | card-fields | funding-eligibility
style: {
borderRadius: 4,
color: 'gold', // gold | blue | silver | white | black
height: 40,
label: 'paypal', // paypal | checkout | buynow | pay | installment | subscribe | donate
layout: 'vertical', // vertical | horizontal
shape: 'rect' // rect | pill | sharp
}
});
// PayPal 不需要监听 completed 事件
// 当支付完成时,SDK 会发起重定向到 merchantResultUrl5. 事件监听
所有支付元素都支持统一的事件模型:
// 监听 ready 事件
applePay.on('ready', () => {
console.log('Apple Pay 已渲染');
});
// 监听 success 事件
applePay.on('success', (event) => {
console.log('Apple Pay 支付完成', event.detail);
// event.detail 包含 transactionId 等信息
});
// 监听 error 事件
applePay.on('error', (event) => {
console.error('Apple Pay 错误', event.detail);
// event.detail 包含 code 和 message
});
// 监听 cancel 事件
applePay.on('cancel', () => {
console.log('Apple Pay 用户取消');
});6. 挂载与卸载
// 挂载到指定容器
applePay.mount('#apple-pay-container');
// 卸载元素
applePay.unmount();API 参考
PingPongSDK.init()
初始化 SDK 配置。
参数:
modeRequiredstring
Payment 或 Vault
envRequiredstring
sandbox 或 production
amountRequiredstring
交易金额
currencyRequiredstring
交易币种
countryRequiredstring
国家/地区代码
如 US、CN、UK 等
accIdRequiredstring
商户账户 ID
localeRequiredstring
界面语言
regionOptionalstring
fra
sg 或 fra
sdkAccessTokenRequiredstring
SDK 访问凭证
merchantResultUrlRequiredstring
支付完成跳转地址
createOrderOptionalFunction
mode 为 Payment 时必传。该函数接收一个包含 payMethod 的对象参数,表示用户选择的支付方式
goodsRequiredArray<GoodsItem>
商品信息数组
biztypeOptionalstring
业务类型
可选值: CodeGrant
recurringInfoDTOOptionalObject
ApplePay 签约必传
PingPongSDK.createElement()
创建支付元素实例。
参数:
typeRequiredstring
applePayButton、googlePayButton、paypalButton
optionsRequiredobject
元素配置参数
返回: Promise<PingPongElement>
element.on()
注册事件监听器。
支持的事件:
readyEvent
元素初始化完成
successEvent
支付成功
errorEvent
支付失败
cancelEvent
用户取消
element.off()
移除事件监听器。
element.mount()
将支付元素挂载到 DOM。
参数:
selectorRequiredstring
CSS 选择器
element.unmount()
从 DOM 中卸载元素,释放资源。