内嵌SDK（预下单）

# Javascript-SDK-2.0 方案一

# 内嵌SDK接入流程

加载中...

内嵌SDK交互流程

# 1. 引入Javascript-SDK

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

<script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-web/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

# 使用方法

提示

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

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

当你在联调沙箱环境时，需要在引入沙箱环境 的PingPongCheckout Javascript-SDK地址（发布到生产环境的时候别忘了切换成生产环境的地址）
将 pp-checkout 标签插入 html body 中
```
<pp-checkout></pp-checkout>
```
1
将预下单获取到的 accessToken 传入，获取accessToken API文档详见下单接口（Hosted模式）
```
<pp-checkout accessToken='{token}'></pp-checkout>
```
1
你可以将收银台所要展示的语种（默认为英文，更多语言详见Locale）通过标签属性的方式传递给 pp-checkout，如下：
```
<pp-checkout locale='en'></pp-checkout>
```
1

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

# 全局变量和hook

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

# 自定义支付按钮（可选）

用户可以自定义按钮，通过点击事件去绑定 pingpong 的支付功能。


    PingPong.Checkout.customizeConfig = {
      originalPay: false
    }

 // 初始化参数中 originalPay 为 false 时, 需自定义支付按钮点击事件
    document.querySelector('#pay').onclick = function () {
        PingPong.Checkout.pay.run()
    }

1
2
3
4
5
6
7
8
9

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

# 是否展示绑卡信息（可选）

控制是否展示绑卡信息，如果设置为 true，即不展示，需要展示的话可以不传，也可以传 false。


    PingPong.Checkout.customizeConfig = {
       hideStoredCards: false
    }

1
2
3
4
5

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

# PingPong.Checkout.beforeCheckoutHook

type：

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

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

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

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

# PingPong.Checkout.checkoutFailedHook

type：

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

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

checkoutFailedHook 接收以下参数：

(code: string, message: string) => void | Promise<void>; 

// code: string - 错误码
// message: string - 错误消息

1
2
3
4

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

checkoutFailedHook 用来自定义错误逻辑

当用户支付失败时，PingPong 默认会弹窗提示用户失败原因。如果你想自定义弹窗 UI 或文本，可以设置该钩子函数。

该函数可以返回一个 Promise。如果返回 Promise，后续的流程会等待该 Promise 状态变为 Fulfilled 后才继续执行

PingPong.Checkout.checkoutFailedHook = (code: string, message: string) => {
    notification.open({
        message: 'Error title',
        description: `${code}: ${message}`
    })
};

1
2
3
4
5
6

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

# PingPong.Checkout.updateBillingHook

type：

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

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

updateBillingHook 接收以下参数：


type UpdateBillingParam = Partial<{
    phone: string;
    city: string;
    state: string;
    street: string;
    country: string;
    postcode: string;
}>

1
2
3
4
5
6
7
8
9
10

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

updateBillingHook 用来更新 billing 信息

updateBillingHook 支持部分字段返回，未返回额度字段将保持原值，可返回同步数据或 Promise。

PingPong.Checkout.updateBillingHook = () => {
    return {
      phone: '',
      city: '',
      state: '',
      street: '',
      country: '',
      postcode:''
} };
// 􏱖􏱔
PingPong.Checkout.updateBillingHook = async () => {
    const billingInfo = await fetchBillingInfo();
    return {
        phone: billingInfo.phone, 
        city: billingInfo.city, 
        // ... 其他字段
} };

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

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

# 使用示例

原生 Javascript

<head>
<script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-web/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

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

如果你使用了 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

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

# Javascript-SDK调试工具

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

# 语种支持

提示

在language未传入的情况下，收银台语言默认为en，如果传了language，就以传入的语言为准。可在语言列表查看具体枚举值

上次更新: 2025/09/12, 15:18:18

← 概览

OnepageSDK→