简体中文

English

简体中文

English

外观

内嵌 SDK

约 14807 字大约 49 分钟

View as Markdown

2026-07-09

PingPong 内嵌 SDK 是基于 SDK 集成的支付组件，旨在帮助商户在自有 Web 页面或移动 App 内快速承载收银台能力，减少支付方式展示、支付交互和客户端适配成本，并为买家提供更连贯的支付体验。

  • Web/WAP 端：适用于浏览器或 H5 页面环境，通过 JavaScript-SDK 在商户页面内渲染 PingPong 收银台。
  • App 端（iOS / Android）：适用于商户自有移动应用，通过 Native SDK 在 App 内唤起半屏收银台。

各端内嵌 SDK 支持的主要能力如下表所示：

特性描述Web/WAPiOSAndroid
支付方式列表渲染SDK 根据支付会话展示可用支付方式，商户无需自行维护支付方式列表和基础交互。支持支持支持
站内嵌入体验支付表单直接嵌入商户 Web/H5 页面，买家可在商户页面内完成支付操作。支持不支持不支持
半屏收银台体验在商户 App 内唤起 PingPong Native SDK 半屏支付面板，支付流程在 App 内完成。不支持支持支持
界面与主题配置支持按端侧能力配置收银台展示效果；Web/WAP 可通过 customizeConfig、customizeStyles 等配置布局、主题和交互。支持不支持不支持
自定义支付按钮Web/WAP 可隐藏 SDK 原生支付按钮，并通过 PingPong.Checkout.pay.run() 由商户自定义按钮触发支付。支持不支持不支持
支付结果回调Web/WAP 可通过 checkoutResultHook 接收前端支付结果；iOS / Android 可通过客户端回调接收结果。商户服务端仍应以支付通知或交易查询确认最终交易状态。支持支持支持
平台选择

接入摘要

内嵌 SDK（预下单）是一种低代码站内收银台方案。商户服务端先调用 prePay（预下单）接口 创建支付会话，再由前端通过 JavaScript-SDK 在商户页面内直接渲染 PingPong 收银台。该方案既能保留买家在商户站内完成支付的体验，也能减少商户自建支付页、支付方式展示和支付交互处理的复杂度。

适用场景

适合希望将收银台直接嵌入商户页面、降低支付页前端开发成本并保留站内支付体验的团队；若可接受买家跳转至 PingPong 托管收银台完成支付，建议选择跳转收银台。

支付体验

Web 支付

在内嵌SDK模式下，您可以将结账体验直接嵌入到自己的网站中。在网页端，结账页面会显示在您的网站内，使客户无需跳转至独立的托管页面即可完成支付。

Web/WAP PC 支付体验示意图
Mobile 支付

在内嵌SDK模式下，允许您将结账体验无缝集成至自有网站中。针对移动端小屏幕进行了专属 UI 优化，客户在手机网页或 App 内即可完成支付，全程无需跳转至外部托管页面，从而提供更流畅、沉浸的移动端支付体验。

Web/WAP Mobile 支付体验示意图

支付流程

  1. 买家下单

    • 买家在商户页面发起结账并提交订单。
    • 商户侧开始创建支付会话，准备初始化内嵌收银台。

  2. 创建支付会话

  3. 初始化并展示收银台

    • 商户前端加载 JavaScript-SDK，并将 accessToken 与 locale 传给 pp-checkout。
    • PingPong 收银台在商户页面内完成渲染并展示可用支付方式。

  4. 买家完成支付

    • 买家选择支付方式、填写支付信息并确认支付。
    • 若触发 3D Secure，买家在当前支付流程中完成验证。

  5. 确认支付结果

    • 支付完成后，前端可通过 checkoutResultHook 接收 SDK 返回的前端支付结果并展示商户自有结果页；未配置 Hook 时，仍按原有结果页或 payResultUrl 逻辑处理。
    • 商户服务端仍需结合异步通知或查询接口确认最终支付状态。

关键注意事项

  1. 支付结果以异步通知（notificationUrl）或对应查询接口确认结果为准，checkoutResultHook 和前端结果页仅用于买家展示；
  2. 优先使用 prePay（预下单）接口 返回的 bizContent.innerJsUrl 动态加载 SDK，以避免环境切换或版本变更带来的地址不一致问题；
  3. ready、error 等事件监听器需要在设置 accessToken 之前注册，否则可能错过初始化事件；
  4. 在 locale 未传入的情况下，收银台默认展示英文；如果传了 locale，则以传入值为准。具体枚举值可参考语言列表。

集成步骤

步骤 1：创建支付会话

在初始化 JS-SDK 收银台之前，商户服务端需要先调用 prePay（预下单）接口 获取 SDK 初始化所需的关键参数。

支付请求关键参数：

参数必填说明
captureDelayHoursO资金请款方式。默认自动请款；如需手动请款，请按支付方式能力和接口规则配置
amountM交易金额
currencyMISO 4217 三位交易币种
merchantTransactionIdM商户网站订单流水号，订单唯一标识
shopperIPM买家下单 IP
merchantUserIdM商户侧用户唯一 ID
goodsM商品信息，至少包含商品名称、单价和数量
customerC买家信息。不同支付方式可能要求邮箱、手机号或账单信息，请以目标支付方式要求为准
paymentMethodsO指定收银台可展示的支付方式范围，不传或为空时按店铺配置展示
notificationUrlO支付结果通知地址，建议传入
payResultUrlO买家完成支付流程后的商户结果页地址
languageO收银台展示语言，未传入时默认展示英文，枚举值参考语言列表

有关完整参数的更多信息，请参阅 prePay（预下单）接口。

支付请求示例：

支付响应示例：

{
  "amount": "1000",
  "currency": "USD",
  "transactionId": "2023092050004591",
  "merchantTransactionId": "PMT-PR5GFUNZQP1695182276082",
  "token": "EU:vr_YVR8u7rn7C1gG97DOg9_-Y66ubtNtoayJ_wiEEzdCnxCHYIk0pXordJYBjq1g",
  "paymentUrl": "https://sandbox-acquirer-payment-ssr.pingpongx.com/v3/checkout?token=...",
  "innerJsUrl": "https://paycdn.pingpongx.com/production/static/sdk/ppPay.min.js?token=..."
}

支付响应关键字段：

参数说明
transactionIdPingPong 交易流水号，用于后续查询、退款、对账
merchantTransactionId商户网站订单流水号
tokenSDK 初始化令牌，用于设置 pp-checkout 的 accessToken 属性
innerJsUrl动态加载 SDK 的 URL，推荐使用此地址加载 JavaScript-SDK
paymentUrl支付页面 URL；如业务后续切换为跳转收银台模式，可直接复用该地址

步骤 2：引入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>

动态获取 SDK 地址（推荐）

除了使用固定的 CDN 地址外，推荐从 prePay（预下单）接口 的响应中动态获取 SDK 地址。

调用 prePay（预下单）接口（POST /v4/payment/prePay）成功后，响应中会返回 bizContent.innerJsUrl 字段，该字段包含当前环境对应的 JS-SDK 地址。

src/utils/loadSDK.js

提示

使用动态获取的 SDK 地址可以确保始终使用与当前环境匹配的最新版本，无需在代码中硬编码环境地址。

步骤 3：初始化并渲染收银台

提示

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

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

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

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

    index.html
    <pp-checkout></pp-checkout>

  3. 将预下单获取到的 accessToken 传入，接口文档详见prePay（预下单）接口

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

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

    index.html
    <pp-checkout locale='en'></pp-checkout>

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

步骤 4：收银台行为与界面配置

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

customizeConfig 布局与界面配置

通过 PingPong.Checkout.customizeConfig 可以自定义收银台的布局和界面元素：

配置项类型默认值说明
layout'tab'|'accordion''tab'页面布局样式，可选值："tab"（标签页样式）、"accordion"（平铺样式）
displayCheckoutHeaderbooleantrue是否显示收银台顶部标题栏
originalPaybooleantrue是否显示原生支付按钮
toPingPongResultbooleantrue支付完成后是否跳转到 PingPong 结果页。false 表示直接跳转到商户配置的结果页面
hideStoredCardsbooleanfalse是否隐藏 COF（Card On File）列表
onlyDisplaySavedCardbooleanfalse设为 true 时，收银台仅展示已存储的卡信息区域（隐藏新卡输入）。适用于 复购 CVV 收集收银台
disableCardRemovalbooleanfalse设为 true 时，禁止用户删除已存储的卡信息。适用于 复购 CVV 收集收银台
displayCardPromptbooleantrue是否显示卡支付提示信息
localizationErrorMsgbooleanfalse是否翻译支付错误消息
displayCardsLogobooleantrue是否显示卡品牌 logo 列表
isChallengeIframebooleanfalse是否使用 iframe 展示 3DS Challenge 页面。设为 true 时，将通过 iframe 承载 Challenge 流程

注意

toPingPongResult 配置需要在服务端创建支付会话时设置。客户端设置可能会被服务端配置覆盖。如需禁用 PingPong 结果页跳转，请确保服务端已正确配置。

src/config/payment.js
// customizeConfig 布局与界面配置
PingPong.Checkout.customizeConfig = {
    layout: "accordion",              // 平铺样式
    displayCheckoutHeader: false,     // 隐藏标题栏
    originalPay: false,               // 隐藏原生支付按钮，需自定义按钮触发支付
    toPingPongResult: false,          // 支付完成后不跳转到 PingPong 结果页
    hideStoredCards: false,           // 显示已保存的卡列表
    displayCardPrompt: true,          // 显示卡支付提示信息
    localizationErrorMsg: false,      // 不翻译错误消息
    displayCardsLogo: true,           // 显示卡品牌 logo
    isChallengeIframe: true           // 使用 iframe 展示 3DS Challenge 页面
};
自定义支付按钮（可选）

当 originalPay 设置为 false 时，需要自定义按钮点击事件来触发支付。

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

customizeStyles 主题样式

通过 PingPong.Checkout.customizeStyles 可以自定义收银台的视觉样式：

配置项类型说明示例值
themeColorstring主题色，支持 CSS 颜色值"rgb(26, 29, 37)", "#1a1d25"
themeColorLightstring主题色浅色变体"rgba(26, 29, 37, 0.4)"
fontFamilystring字体系列"'Montserrat', sans-serif"
src/config/styles.js
// 品牌定制：深色主题
PingPong.Checkout.customizeStyles = {
    themeColor: "rgb(26, 29, 37)",          // 主题色
    themeColorLight: "rgba(26, 29, 37, 0.4)", // 主题色浅色变体
    fontFamily: "'Montserrat', 'PingFang SC', 'Microsoft YaHei', sans-serif"
};

提示

主题色和字体配置需在 SDK 加载完成后、设置 accessToken 之前进行。

PingPong.Checkout.beforeCheckoutHook

type：

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

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

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

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

src/hooks/beforeCheckout.js
// 支付前钩子：检查库存
PingPong.Checkout.beforeCheckoutHook = () => {
    return fetch('/api/requestInventory').then(res => {

        const { inventoryQuantity } = res;

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

PingPong.Checkout.checkoutResultHook

type：

(payload: CheckoutResultHookPayload) => void | Promise<void>

checkoutResultHook 用于接收 SDK 前端可直接得到的支付结果，并由商户前端接管支付完成后的页面展示或跳转。请在用户发起支付前注册该 Hook。该 Hook 挂载在 PingPong.Checkout 上，不是 <pp-checkout> 标签属性。

checkoutResultHook 会把支付结果统一收敛为以下三种状态：

状态含义建议处理
success支付成功展示商户成功页，或跳转到商户成功页
pending支付处理中或待确认，包含 SDK 内部的 PENDING、PROCESSING、REVIEW 等非终态场景展示处理中页面，并通过服务端查询或异步通知确认最终结果
failed支付失败展示失败页，提供重试或返回商户站点的入口

Payload 类型定义：

src/types/checkout-result.ts
type CheckoutResultHookPayload = {
    status: 'success' | 'pending' | 'failed';
    code: string;
    message: string;
    merchantTransactionId?: string;
    paymentMethod?: string;
};

Payload 字段说明：

字段类型是否必返说明
statussuccess | pending | failedMSDK 归一化后的前端支付结果
codestringM支付结果码或错误码；无特定错误时可能返回 0
messagestringM支付结果描述或错误描述
merchantTransactionIdstringO商户订单号
paymentMethodstringO支付方式

Payload 示例：

{
  "status": "pending",
  "code": "0",
  "message": "Payment is processing",
  "merchantTransactionId": "ORDER_202607200001",
  "paymentMethod": "VISA"
}

接入示例：

src/hooks/checkoutResult.js

触发与跳转规则：

商户配置success / pending 场景failed 场景结果页跳转
未配置 Hook不触发 Hook不触发 Hook保持原有结果页跳转逻辑
仅配置 checkoutResultHook触发 checkoutResultHook触发 checkoutResultHook命中 Hook 后不再跳转 PingPong 结果页
仅配置 checkoutFailedHook不触发 Hook触发 checkoutFailedHook保持原有失败处理逻辑
同时配置两个 Hook触发 checkoutResultHook优先触发 checkoutFailedHook失败场景不重复回调

建议新接入商户优先配置 checkoutResultHook。如果历史上已经接入 checkoutFailedHook，请在确认业务兼容后再迁移到 checkoutResultHook，避免同一失败结果被重复处理。

注意

  • checkoutResultHook 是浏览器侧回调，不能作为商户后台更新订单状态的唯一依据。最终支付结果请以 PingPong 服务端异步通知或订单查询接口为准。
  • 如果同时配置 checkoutResultHook 和 checkoutFailedHook，支付失败场景会优先触发 checkoutFailedHook，SDK 不会再重复触发 checkoutResultHook。如需由一个 Hook 统一处理 success、pending、failed，请只配置 checkoutResultHook。
  • pending 不是失败。请展示处理中状态，并在商户后台继续等待最终支付结果。
  • Hook 支持返回 Promise，SDK 会等待 Promise 完成。请避免在 Hook 内执行长时间阻塞逻辑。
  • Hook 内部异常不会恢复 PingPong 结果页跳转。商户应在 Hook 内自行处理异常，并准备兜底页面。
  • 需要跳转到 3DS 认证页面，或渠道返回 redirectUrl、中间页地址时，SDK 仍会继续执行原有跳转流程。

PingPong.Checkout.checkoutFailedHook

type：

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

checkoutFailedHook 接收以下参数：

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

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

checkoutFailedHook 用来自定义错误逻辑

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

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

src/hooks/checkoutFailed.js
// 支付失败钩子：自定义错误提示
PingPong.Checkout.checkoutFailedHook = (code: string, message: string) => {
    notification.open({
        message: 'Error title',
        description: `${code}: ${message}`
    })
};

事件监听（可选）

SDK 支持监听初始化过程中的 ready 和 error 事件，方便外部进行状态管理和错误处理。

src/config/payment.js
// 监听 SDK 初始化事件
// 监听初始化成功事件
document.querySelector('pp-checkout').addEventListener('ready', (e) => {
    console.log('SDK初始化成功'); // 初始化成功回调
    // 可以在此处执行初始化完成后的逻辑，如隐藏加载动画
});

// 监听初始化失败事件
document.querySelector('pp-checkout').addEventListener('error', (e) => {
    console.log('SDK初始化失败', e.detail); // 错误信息
    // 可以在此处执行错误处理逻辑，如显示错误提示、重试等
});

事件说明:

  • ready: 当 SDK 初始化成功时触发，表示收银台已准备就绪。event.detail 包含 SDK 实例信息
  • error: 当 SDK 初始化失败时触发，如 accessToken 无效、网络错误等。event.detail 包含 { message, code } 错误信息

注意

事件监听器必须在 setAttribute 之前添加，否则可能无法捕获事件。

src/config/payment.js
// ❌ 错误：先设置属性再添加监听器
ppCheckout.setAttribute('accessToken', token);
ppCheckout.addEventListener('ready', handler);  // 可能无法触发！

// ✅ 正确：先添加监听器再设置属性
ppCheckout.addEventListener('ready', handler);
ppCheckout.setAttribute('accessToken', token);

使用示例

原生 JavaScript 完整示例

以下示例展示了如何在原生 JavaScript 项目中集成 SDK，包含完整的项目结构、API 调用和错误处理。

原生 JavaScript 集成示例

index.html

styles.css

config.js

api.js

main.js

index.html
styles.css
config.js
api.js
main.js

Vue 3 完整示例

以下示例展示了如何在 Vue 3 项目中集成 SDK，使用 Composition API 实现响应式状态管理。

Vue 3 集成示例

App.vue

api

checkout.js

config

index.js

composables

useCheckout.js

index.html

main.js

App.vue
api/checkout.js
config/index.js
composables/useCheckout.js
index.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>PingPong Checkout SDK - Vue 3 示例</title>
  <!-- 引入沙箱环境 SDK -->
  <script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-web/sandbox/pp-checkout.js"></script>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.js"></script>
</body>
</html>
main.js
import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);
app.mount('#app');

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

支付后操作

以下支付后操作适用于 Web/WAP、iOS 和 Android 集成形态，相关操作均由商户服务端完成。前端结果页或 SDK 回调只用于买家展示与交互反馈，不应直接作为订单最终成功依据；订单状态仍应以 支付通知 或 交易查询 的服务端确认结果为准。

查询交易

当买家从结果页返回、App 收到支付完成回调、异步通知延迟或未达，或商户需要执行补偿任务时，可以调用 交易查询 获取交易最新状态。

查询时建议优先使用商户侧保存的 merchantTransactionId 或 PingPong 返回的 transactionId 定位交易；查询请求成功仅表示查询接口处理成功，不代表支付成功，商户订单状态仍应以查询响应中的 status 为准。

退款

支付成功后，如买家申请退款、商户取消已支付订单或需要退回部分或全部款项，可调用 申请退款 对原交易发起退款。

退款结果可通过 退款通知 接收；如通知延迟、未达或需要再次确认，可调用 退款查询 主动查询。

不同支付方式的退款能力不同，接入前请确认目标支付方式是否支持退款、退款有效期、是否支持部分退款以及是否支持多次部分退款。更完整的退款接入说明可参考 Refund。

对账

如需了解账单生成规则与结算周期，可参考 结算周期和对账单；如需开通账单下载能力，可参阅 SFTP服务申请。

Home page PingPongCheckout
Copyright ©2015-2026 杭州乒乓智能技术有限公司 All Rights Reserved.