Javascript-SDK-2.0对接文档

# Javascript-SDK-2.0对接文档

# Javascript-SDK-2.0新特性

基于 Web Component 技术，由浏览器原生支持的，优势明显
更加轻量，快速响应，Gzip后整个收银台包大小约为 59 kb
对接方式简单，灵活接入，符合现代化收银台 web app 标准
现代主流浏览器中高版本均兼容
支持自定义 SDK 收银台皮肤
支持发起支付请求前设置钩子函数
支持自定义支付按钮触发支付事件

# 收银台结果页展示

当用户选择支付方式后并完成支付后，系统将根据图片展示逻辑重定向到其支付结果页面

# 浏览器最低版本要求

⁷³

⁷⁹

⁶³

^12.1

# 接入流程

# 引入Javascript-SDK

复制以下代码，通过CDN地址引入 PingPongCheckout Javascript-SDK

<script type="module" src="https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js"></script>

<script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-web/pp-checkout.js"></script>

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

# 初始化JS-SDK

提示

从沙箱环境切换到生产环境时，请务必检查并且完成下列的操作，否则会导致收银台无法正常渲染。

将引入Javascript-SDK的CDN地址切换到生产环境指定的URL

Step 1 . 当你在联调沙箱环境时，需要在引入沙箱环境 的PingPongCheckout Javascript-SDK地址（发布到生产环境的时候别忘了切换成生产环境的地址）

Step 2 . 将 pp-checkout 标签插入 html body 中

<pp-checkout></pp-checkout>

Step 3 . 将预下单获取到的 accessToken 传入，获取accessToken API文档详见下单接口（Hosted模式）

<pp-checkout accessToken='{token}'></pp-checkout>

Step 4 . 设置语言，你可以将收银台所要展示的语种（默认为英文，更多语言详见Locale）通过标签属性的方式传递给 pp-checkout，如下：

<pp-checkout locale='en'></pp-checkout>

通过上面四步，你已经成功渲染了Javascript-SDK收银台。

# 使用示例

原生 Javascript

<head>
<script type="module" src="https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js"></script>
</head>
<body>
    <div id="checkout-wrap">
        <pp-checkout accessToken="" locale="zh"></pp-checkout>
    </div>


    <script>
        new Promsie((resolve, reject) => {
            // Mock 预下单获取 token
            setTimeout(() => {
                // 下单接口（Hosted模式）获取 token
                const token = 'EU:7GKJGJxK7hZtmuTAs5I9G-TPWeHkcZt7J4awedWETYteVyVpmhBjEzR2aWc6--Mv';
                document.querySelector('pp-checkout').setAttribute('accessToken', token);
                resolve();
            }, 2000)
        })
    </script>
</body>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

如果你使用了 Vue/React 等框架，直接修改数据源即可:

<template>
  <div id="checkout-wrap">
    <pp-checkout :accessToken="accessToken" locale="zh"></pp-checkout>
  </div>
</template>
<script setup>
import { ref, onBeforeMount } from 'vue';

const accessToken = ref('');

function getOrderInfo() {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            accessToken.value = 'EU:7GKJGJxK7hZtmuTAs5I9G-TPWeHkcZt7J4awedWETYteVyVpmhBjEzR2aWc6--Mv';
            resolve();
        }, 1000);
    });
}

onBeforeMount(async () => {
    await getOrderInfo();
});
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# SDK 个性化设置

# 全局变量和hook

在使用全局变量前，请确保Javascript-SDK 加载完成。

PingPong.Checkout.customizeStyles

{
    themeType?: 'light' | 'dark' // 不传默认为 light;
    themeColor: string;
    themeColorLight: string;
}

1
2
3
4
5

v4 SDK 支持自定义皮肤，当你需要将 SDK 收银台主题色改为符合你的网站风格时，这很有用。示例：

PingPong.Checkout.customizeStyles = {
    themeType: "light" ,
    themeColor: "rgb(54, 175, 3)",
    themeColorLight: "rgba(54, 175, 3, 0.4)",
}

1
2
3
4
5

PingPong.Checkout.beforeCheckoutHook

(() => void) | (() => Promise<void>)

beforeCheckoutHook 用来设置发起支付请求前的钩子函数。

当你在用户点击支付按钮，发起支付请求前，需要执行你自己的业务逻辑，如：上报埋点、检查库存等，可以设置该钩子函数。

该函数可以返回一个Promise，后续的支付流程会等待该 Promise 状态变为 Fulfilled 后才会继续执行。如果你想在 Promise 状态为 Rejected 或者异步结果不满足你的业务条件时，可以抛出异常，SDK在捕获到异常后中断支付流程。

示例

PingPong.Checkout.beforeCheckoutHook = () => {
    return fetch('/api/requestInventory').then(res => {

        const { inventoryQuantity } = res;

        if(inventoryQuantity <  MIN_QUANTITY) {
            throw new Error('库存不足，需中断交易')
        }
    }).catch((error) => {
        throw new Error('接口异常，需中断交易')
    })
};

1
2
3
4
5
6
7
8
9
10
11
12

# 自定义配置

# PingPong.Checkout.customizeConfig

类型: Object

PingPong.Checkout.customizeConfig 是一个自定义配置对象，用于设置与 Checkout 过程相关的参数。

配置项说明:

Key（键）	类型（Type）	默认值（Default）	描述（Description）
originalPay	boolean	true	控制是否使用默认的 PingPong 支付按钮。若将其设置为 `false`，则表示不使用内置支付按钮。此时，您需要在您的自定义支付按钮点击事件中调用 `PingPong.Checkout.pay.run()` 方法来触发支付流程。

const customizeConfig = {
  originalPay: false, // 不使用默认的 PingPong 支付按钮
};

// 在自定义按钮点击事件处理函数中触发支付
customPayButton.addEventListener('click', () => {
  PingPong.Checkout.pay.run();
});

1
2
3
4
5
6
7
8

# Javascript-SDK调试工具

你可以在沙箱环境中体验 Javascript-SDK 的功能，请前往Javascript-SDK 调试工具。

上次更新: 2024/03/14, 10:34:54