简体中文

English

简体中文

English

外观

OnePage Checkout

约 10077 字大约 34 分钟

View as Markdown

2025-03-07

接入摘要

OnePage Checkout 是适用于一页式结账场景的站内支付组件方案。商户服务端先调用 获取 sdkAccessToken 接口 获取初始化凭证，商户前端再在现有结账页面中引入 OnePage JavaScript-SDK 并渲染 PingPong 支付组件。买家点击支付后，商户前端通常还需要通过 beforeCheckoutHook 调用商户后端创建订单，由商户后端进一步调用 prePay（预下单）接口 获取支付 token，并返回给 SDK 发起支付。该方案能够让地址、配送、订单摘要与支付区域在同一页面联动，减少页面跳转，同时保留商户站内结账体验。

适用场景

适合已经采用 OnePage Checkout 结账页，且需要在同一页面内联动金额、国家、商品信息与支付组件的团队；若只需要通用站内收银台，可参考内嵌 SDK。

支付流程

  1. 获取初始化凭证

    • 商户服务端调用 获取 sdkAccessToken 接口。
    • 获取用于初始化 OnePage Checkout 的 sdkAccessToken，并返回给前端页面。

  2. 初始化收银台

    • 商户前端引入与环境匹配的 OnePage JavaScript-SDK。
    • 在结账页插入 pp-checkout 组件，并调用 PingPong.Checkout.create() 传入 amount、currency、tradeCountry、sdkAccessToken 等参数。

  3. 渲染并联动支付组件

    • PingPong 支付组件在商户结账页内完成渲染并展示可用支付方式。
    • 当金额、国家或商品信息变化时，可调用 updateCheckoutHook 对收银台做局部更新。

  4. 创建支付订单

    • 买家在当前结账页内选择支付方式并点击支付按钮。
    • SDK 触发 beforeCheckoutHook 后，商户前端可调用商户后端创建订单。
    • 商户后端再调用 prePay（预下单）接口 获取支付 token，并将该 token 返回给前端。
    • 前端在 beforeCheckoutHook 中将支付 token 返回给 SDK。

  5. 提交支付并处理结果

    • SDK 拿到支付 token 后，才会正式向 PingPong 发起支付请求。
    • 支付成功或处理中时，可通过 checkoutResultHook 接收前端支付结果，并更新当前结账页状态或进入后续结果展示流程。
    • 支付失败时，可使用 checkoutResultHook 统一接收失败结果；如历史上已配置 checkoutFailedHook，失败场景会优先走 checkoutFailedHook。

关键注意事项

  1. sdkAccessToken 仅用于初始化 OnePage Checkout，不等同于支付时使用的订单 token；
  2. 支付 token 需要在买家点击支付后，由商户后端调用 prePay（预下单）接口 创建订单并返回给前端 SDK；
  3. 请确保引入的 OnePage JavaScript-SDK 地址与当前运行环境一致，避免沙箱与生产环境脚本混用；
  4. updateCheckoutHook 采用局部更新机制，只传入发生变化的字段即可，无需重复传未变化参数；
  5. 当 originalPay 设置为 false 时，需要由商户自定义支付按钮并手动调用 PingPong.Checkout.pay.run() 触发支付；
  6. 若配置 paymentMethods 参数，实际展示结果会与当前 accId 已开通的支付方式取交集，展示顺序以传入数组顺序为准；
  7. checkoutResultHook 是浏览器侧回调，仅用于前端页面展示或跳转，最终支付结果仍应以服务端异步通知或交易查询为准。

集成流程

1. 获取 sdkAccessToken

商户后端系统通过获取 sdkAccessToken 接口 得到 JS-SDK 访问凭证（token），该凭证用于前端 JS-SDK 的初始化调用。

2. 引入 JavaScript-SDK

复制以下代码，通过 CDN 地址引入 PingPong OnePage JavaScript-SDK。

🧪 沙箱环境
<script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-onepage/sandbox/pp-checkout.js"></script>

3. 初始化收银台

将 pp-checkout 标签插入 html body 中

components/checkout.html
<!-- 插入 PingPong 收银台组件 -->
<pp-checkout locale="en"></pp-checkout>

调用 PingPong.Checkout.create 完成初始化

入参

amountRequiredString

交易金额

该交易仅用于收银台展示，后续金额变更需调用 updateCheckoutHook 函数进行更新

currencyRequiredString

交易币种

tradeCountryRequiredString

用于指定 PingPong 收银台国家

后续国家变更需调用 updateCheckoutHook 函数进行更新

sdkAccessTokenRequiredString

JS-SDK 访问凭证

originalPayOptionalBoolean

true

控制是否使用默认的 PingPong 支付按钮

若将其设置为 false，则表示不使用内置支付按钮。此时，需要在页面内自定义支付按钮点击事件中调用 PingPong.Checkout.pay.run() 方法来触发支付流程。

isChallengeIframeOptionalBoolean

false

控制是否使用 iframe 展示 3DS Challenge 页面

当设置为 true 时，将通过 iframe 承载 Challenge 流程。

paymentMethodsOptionalString[]

指定支付方式列表，内嵌收银台会根据指定的支付方式进行展示

传入的支付方式将与该 accId 下配置的支付方式进行交集运算。支付方式的展示顺序将根据传入数组的顺序进行排列。

useTabModeOptionalBoolean

true

控制是否展示支付方式选项框

当设置为 false 时，如果商户仅有卡支付配置，将不展示选项框，直接显示支付表单。适用于简化用户体验的场景。

goodsOptionalArray

商品列表，包含以下子字段

goods.descriptionOptionalString

商品描述

goods.imgUrlOptionalString

商品图片 URL

goods.nameRequiredString

商品名称

goods.numberRequiredString

商品数量

goods.skuOptionalString

商品 SKU 编码

goods.unitPriceRequiredString

商品单价

goods.virtualProductOptionalString

N

是否为虚拟商品

Y - 虚拟商品，N - 实物商品

bizTypeOptionalString

ApplePay 绑卡业务参数

ApplePay 交易必传，固定值: CodeGrant

recurringInfoDTOOptionalObject

配置 Recurring 付款（ApplePay 交易必传），包含以下子字段

recurringInfoDTO.recurringPaymentStartDateOptionalDate

首次付款日期

eg: "2024-06-01 00:00:00"

recurringInfoDTO.recurringPaymentIntervalUnitOptionalString

表示年、月、日、时等日历单位的类型

enum: year / month / day / hour / minute，eg: "month"

recurringInfoDTO.recurringPaymentIntervalCountOptionalString

构成总支付间隔的间隔单位数

eg: "6"

recurringInfoDTO.recurringPaymentEndDateOptionalDate

最后付款日期

eg: "2024-12-01 00:00:00"

自定义支付按钮（可选）

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

事件监听（可选）

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 初始化成功时触发，表示收银台已准备就绪
  • error: 当 SDK 初始化失败时触发，事件详情包含在 e.detail 中

4. 修改金额、国家和商品

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

updateCheckoutHook（可选）

updateCheckoutHook 用来更新收银台要素。

ts 类型
src/types/hooks.ts
// updateCheckoutHook 类型定义
PingPong.Checkout.updateCheckoutHook:
({ amount?: string, tradeCountry?: string, goods?: Goods[] }) => void
使用说明

⚠️ 重要：该方法采用部分更新机制，只需传入发生变化的字段即可，无需传入其他字段。

场景传入参数示例代码
国家发生变化tradeCountryPingPong.Checkout.updateCheckoutHook({ tradeCountry: newCountry });
金额发生变化amountPingPong.Checkout.updateCheckoutHook({ amount: newAmount });
商品发生变化goodsPingPong.Checkout.updateCheckoutHook({ goods: newGoods });
正确示例
src/config/update.js
❌ 错误示例

以下方式不推荐，传入不必要的字段或 null 值：

src/config/update-error.js
// ❌ 错误: 不需要传入未变化的字段，也不需要传入 null
PingPong.Checkout.updateCheckoutHook({
    amount: newAmount ? newAmount : null,
    tradeCountry: newCountry ? newCountry : null,
    goods: newGoods ? newGoods : null
});

// ❌ 错误: 只更新金额时，不需要同时传入 country 和 goods
PingPong.Checkout.updateCheckoutHook({
    amount: '99.99',
    tradeCountry: 'US',  // 未变化的字段，不需要传
    goods: []             // 未变化的字段，不需要传
});

5. 下单前检验

beforeCheckoutHook（可选）

type：

src/types/hooks.ts
// beforeCheckoutHook 类型定义
(({payMethod}) => void) | (({payMethod}) => Promise<void>)

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

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

该函数接收一个包含 payMethod 的对象参数，表示用户选择的支付方式。

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

典型接入方式

OnePage Checkout 的常见接法是：商户前端在 beforeCheckoutHook 中调用商户后端创建订单，商户后端再调用 prePay（预下单）接口 获取支付 token，最后由 beforeCheckoutHook 将该 token 返回给 SDK，SDK 再继续提交支付。

src/config/payment.js
ts 类型
src/types/hooks.ts
// beforeCheckoutHook 返回类型定义
PingPong.Checkout.beforeCheckoutHook:
(({payMethod}) => string) | (({payMethod}) => Promise<string>)

6. 发起支付

买家点击支付按钮后，SDK 会先等待 beforeCheckoutHook 返回支付 token；在拿到由商户后端调用prePay（预下单）接口创建的支付 token 后，才会继续发起支付请求并完成支付处理。

7. 支付结果处理

checkoutResultHook（可选）

type：

src/types/hooks.ts
// checkoutResultHook 类型定义
(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": "success",
  "code": "0",
  "message": "Payment successful",
  "merchantTransactionId": "ORDER_202607200001",
  "paymentMethod": "VISA"
}

接入示例：

src/config/payment.js

触发与跳转规则：

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

注意

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

8. 错误处理

checkoutFailedHook（可选）

type：

src/types/hooks.ts
// checkoutFailedHook 类型定义
(() => void) | (() => Promise<void>)

checkoutFailedHook 接收以下参数：

src/types/hooks.ts
// checkoutFailedHook 参数类型定义
(code: string, message: string) => void | Promise<void>;

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

checkoutFailedHook 用来自定义错误逻辑

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

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

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

使用示例

PingPong Checkout 集成示例

examples

onepage

pages

checkout.html

assets

css

checkout.css

js

config

app-config.js

services

pingpong-service.js

utils

ui-utils.js

main.js

examples/onepage/pages/checkout.html
examples/onepage/assets/css/checkout.css
examples/onepage/js/config/app-config.js
examples/onepage/js/services/pingpong-service.js
examples/onepage/js/utils/ui-utils.js
examples/onepage/js/main.js

常见问题

Q1: 为什么我的结账流程无法启动，系统提示 beforeCheckoutHook 相关错误？

A: 当系统提示 "The beforeCheckoutHook is not defined or is not a function" 时，表明您的 one-page sdk 配置中缺少有效的 beforeCheckoutHook 函数。请确保在配置中正确定义此函数，它是启动结账流程的必要条件。

Q2: 我已定义 beforeCheckoutHook 函数，但仍收到 token 相关错误，如何解决？

A: 错误 "Invalid or missing token returned by beforeCheckoutHook" 表明您的 beforeCheckoutHook 函数未返回有效的 token。请确保该函数返回一个非空字符串类型的 token，这是支付处理的必要凭证。

Q3: 创建支付时，系统提示 amount 参数错误，应如何处理？

A: 当系统显示 "Invalid or missing amount: must be a non-empty string" 时，表明您提供的 amount 参数不符合要求。请确保 amount 参数是非空字符串类型，例如 "10.99"。

Q4: 如何确保我使用的货币代码有效？

A: 系统支持特定的货币代码列表。如果收到 "Invalid or missing currency" 错误，请检查您提供的货币代码是否在支持列表中。常用的代码包括 "USD"、"EUR"、"CNY" 等。完整列表请参考 API 文档。

Q5: sdkAccessToken 验证失败的原因是什么？

A: 错误 "Invalid or missing sdkAccessToken" 表明您提供的 sdkAccessToken 无效或缺失。请确保提供一个有效的、非空字符串类型的 sdkAccessToken，这是身份验证的关键凭证。

Q6: 配置 paymentMethods 时需要注意什么？

A: 如果您选择配置 paymentMethods 参数，必须确保它是数组类型。若收到 "Invalid paymentMethods: must be an array or undefined" 错误，请检查您提供的值是否为数组，或考虑完全移除此参数以使用默认支付方式。

Q7: 如何确保 one-page sdk 配置的正确性？

A: 建议在实施前全面测试您的配置。特别注意：

  • beforeCheckoutHook 函数必须正确定义并返回有效 token
  • 所有必需参数（amount、currency、sdkAccessToken）必须符合类型要求
  • 可选参数如 paymentMethods 必须符合预期格式

Q8: 支付流程中断时如何快速排查问题？

A: 请检查控制台错误信息，它通常会精确指出问题所在。根据错误信息对照本 FAQ 进行相应调整。如果问题持续，请确保您使用的是最新版本的 SDK，并查阅完整的技术文档。

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