PingPong Element SDK 集成指南

约 2260 字大约 8 分钟

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>

🇪🇺 FRA 生产环境

<script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/production/v1/index.js"></script>

🇸🇬 SG 生产环境

<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 签约必传

初始化示例

src/sdk-init.js
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

示例:

src/goods-example.js
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 按钮

src/apple-pay.js
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 按钮

src/google-pay.js
const googlePay = await PingPongSDK.createElement('googlePayButton', {
  buttonType: 'buy',     // 按钮类型: buy | subscribe
  buttonColor: 'black',  // 按钮颜色: black | white
  isChallengeIframe: true, // 使用 iframe 展示 3DS Challenge 页面
  style: {
    width: '100%',
    height: '40px',
    borderRadius: '4px'
  },
  payDiscount: {
    activityNo: 'EEE',
    costAmount: '19.99',
    discountAmount: '2.00'
  }
});

Google Pay options 参数:

buttonTypeOptionalstring

按钮类型，可选值：buy、subscribe

buttonColorOptionalstring

按钮颜色，可选值：black、white

isChallengeIframeOptionalboolean

是否使用 iframe 展示 3DS Challenge 页面。当设置为 true 时，将通过 iframe 承载 Challenge 流程。

styleOptionalobject

按钮样式配置

payDiscountOptionalobject

营销活动配置

4.3 PayPal 按钮

src/paypal.js
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 会发起重定向到 merchantResultUrl

5. 事件监听

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

src/event-listeners.js
// 监听 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. 挂载与卸载

src/lifecycle.js
// 挂载到指定容器
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 中卸载元素,释放资源。

无代码接入

开发者接入

PingPong 收银台

Native SDK

合规接入指南

Direct API

PingPong Element SDK 集成指南

SDK集成流程

架构设计

核心模块

支付模式

接入流程

1. 获取 sdkAccessToken

2. 引入 Element SDK

3. 初始化 SDK

入参说明

初始化示例

goods 数组结构

4. 创建支付元素

4.1 Apple Pay 按钮

4.2 Google Pay 按钮

4.3 PayPal 按钮

5. 事件监听

6. 挂载与卸载

API 参考

PingPongSDK.init()

PingPongSDK.createElement()

element.on()

element.off()

element.mount()

element.unmount()