PingPong Element SDK - 重构版集成指南

加载中...

Element 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>

// Make sure to add code blocks to your code group

3. 初始化 SDK

入参说明

字段	类型	必填	描述
mode	string	是	业务模式:Payment(支付) 或 Vault( PayPal 做独立签约用)
env	string	是	运行环境:sandbox(沙箱) 或 production(生产)
amount	string	是	交易金额,用于收银台展示
currency	string	是	交易币种
country	string	是	国家/地区代码,如 US、CN 等
accId	string	是	商户账户 ID
locale	string	是	界面语言:en、zh-CN 等
region	string	否	地区:sg 或 fra(默认 fra)
sdkAccessToken	string	是	SDK 访问凭证
merchantResultUrl	string	是	支付完成后的跳转地址
createOrder	Function	条件	下单函数,mode 为 Payment 时必传
goods	Array	否	商品信息数组
biztype	string	否	业务类型,可选值 CodeGrant
recurringInfoDTO	Object	条件	Recurring 配置,ApplePay 签约必传

goods 数组结构:

字段	类型	必填	描述
name	string	是	商品名称
description	string	否	商品描述
imgUrl	string	否	商品图片 URL
sku	string	否	商品 SKU
unitPrice	string	是	商品单价
number	string	是	商品数量
virtualProduct	string	否	是否为虚拟产品:Y 或 N

初始化示例

await PingPongSDK.init({
  mode: 'Payment',
  env: 'sandbox',
  amount: '19.99',
  currency: 'USD',
  country: 'US',
  accId: 'ACC_123',
  locale: 'en',
  region: 'fra',
  sdkAccessToken: 'your_sdk_token',
  merchantResultUrl: 'https://merchant-result.com',

  // mode 为 Payment 时必传
  createOrder: async () => {
    const response = await fetch('/xx/xx', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        xx: 'xx'
      })
    });
    const result = await response.json();
    return result.token;
  },

  // 商品信息(必填)
  goods: [{
    "description": "short legs",
    "imgUrl": "http://pic.bizhi360.com/bpic/30/5230.jpg",
    "name": "한국어/English",
    "number": "1",
    "sku": "20230524001",
    "unitPrice": "1",
    "virtualProduct": "N"
  }],

  // 可选参数
  biztype: 'CodeGrant',

  // ApplePay 签约时必传
  recurringInfoDTO: {
    recurringPaymentStartDate: '2024-06-01 00:00:00',
    recurringPaymentIntervalUnit: 'month',
    recurringPaymentIntervalCount: '6',
    recurringPaymentEndDate: '2024-12-01 00:00:00'
  }
});

// Make sure to add code blocks to your code group

4. 创建支付元素

4.1 Apple Pay 按钮

const applePay = await PingPongSDK.createElement('applePayButton', {
  buttonType: 'buy',
  buttonColor: 'black',
  style: {
    width: '100%',
    height: '40px',
    borderRadius: '4px'
  },
  payDiscount: {
    activityNo: 'EEE',
    costAmount: '19.99',
    discountAmount: '2.00'
  }
});

// Make sure to add code blocks to your code group

4.2 Google Pay 按钮

const googlePay = await PingPongSDK.createElement('googlePayButton', {
  buttonType: 'buy',
  buttonColor: 'black',
  style: {
    width: '100%',
    height: '40px',
    borderRadius: '4px'
  },
  payDiscount: {
    activityNo: 'EEE',
    costAmount: '19.99',
    discountAmount: '2.00'
  }
});

// Make sure to add code blocks to your code group

4.3 PayPal 按钮

const paypal = await PingPongSDK.createElement('paypalButton', {
  buttonType: 'buttons',
  style: {
    borderRadius: 4,
    color: 'gold',
    height: 40,
    label: 'paypal',
    layout: 'vertical',
    shape: 'rect'
  }
});

// Make sure to add code blocks to your code group

提示

PayPal 不需要监听 completed 事件,当支付完成时,SDK 会发起重定向到 merchantResultUrl

5. 事件监听

所有支付元素都支持统一的事件模型:

// 监听 ready 事件
applePay.on('ready', () => {
  console.log('Apple Pay 已渲染');
});

// 监听 success 事件
applePay.on('success', (event) => {
  console.log('Apple Pay 支付完成', event.detail);
});

// 监听 error 事件
applePay.on('error', (event) => {
  console.error('Apple Pay 错误', event.detail);
});

// 监听 cancel 事件
applePay.on('cancel', () => {
  console.log('Apple Pay 用户取消');
});

// Make sure to add code blocks to your code group

6. 挂载与卸载

// 挂载到指定容器
applePay.mount('#apple-pay-container');

// 卸载元素
applePay.unmount();

// Make sure to add code blocks to your code group

API 参考

PingPongSDK.init()

初始化 SDK 配置。

参数:

参数	类型	必填	描述
mode	string	是	Payment 或 Vault
env	string	是	sandbox 或 production
amount	string	是	交易金额
currency	string	是	交易币种
country	string	是	国家/地区代码,如 US、CN 等
accId	string	是	商户账户 ID
locale	string	是	界面语言
region	string	否	sg 或 fra(默认)
sdkAccessToken	string	是	SDK 访问凭证
merchantResultUrl	string	是	支付完成跳转地址
createOrder	Function	条件	mode 为 Payment 时必传
goods	Array	是	商品信息数组
biztype	string	否	业务类型,可选值 CodeGrant
recurringInfoDTO	Object	条件	ApplePay 签约必传

PingPongSDK.createElement()

创建支付元素实例。

参数:

参数	类型	必填	描述
type	string	是	applePayButton、googlePayButton、paypalButton
options	object	是	元素配置参数

返回: Promise<PingPongElement>

element.on()

注册事件监听器。

支持的事件:

事件	描述
ready	元素初始化完成
success	支付成功
error	支付失败
cancel	用户取消

element.off()

移除事件监听器。

element.mount()

将支付元素挂载到 DOM。

参数:

参数	类型	必填	描述
selector	string	是	CSS 选择器

element.unmount()

从 DOM 中卸载元素,释放资源。