PayKKa Checkout UI Component 使用文档

安装

PayKKa Checkout UI 支持通过 npm 或 CDN 进行引入：

npm

安装 @paykka/card-checkout-ui：

npm

pnpm

yarn

为了正常的展示组件，需要全局引入样式：

CDN

通过 CDN 链接引入组件样式和脚本：

脚本加载成功后会创建一个全局对象 PaykkaCardCheckoutUI，所有组件和方法都由该对象暴露出来，你可以这样使用：

初始化

在正式使用组件之前，您需要初始化 PayKKa 收银台实例：

这之后代码中的收银台实例统称为 paykkaCheckout。

npm

CDN

目前您可以在创建收银台时进行如下配置：

必填参数用 * 标识

名称	说明	类型	默认值
*sessionId	收银台 ID，用来创建收银台	`string`
*clientKey	客户端密钥	`string`
locale	语言，用于收银台文案展示	`string`	`'en-GB'`
hidePaymentButton	是否展示支付按钮	`boolean`	`true`
fraudDetectionEnv	欺诈检测环境配置	`'eu' \| 'hk'`	`'eu'`
sandbox	是否使用沙箱环境	`boolean`	`false`
onPaymentMethodsReady	收银台已经获取到可用支付方式时调用	`(methods: string[]) => void`	`undefined`
onInitError	收银台初始化时报错触发	`(error: any) => void`	`undefined`

下面是对一些配置的详细说明：

hidePaymentButton

hidePaymentButton 用来配置是否展示 PayKKa 内置的支付按钮。

如果您想用自己的支付按钮，可以将 hidePaymentButton 配置为 true 来隐藏 PayKKa 的支付按钮，用户点击您的支付按钮后，可以调用组件实例暴露出的 payment 方法进行支付。

下面用 Card 组件举个例子：

npm

CDN

locale

目前 PayKKa Checkout UI 支持如下 11 种国际化语言，按照 IETF BCP 47 格式展示：

de-DE：德语（德国）

en-GB：英语（英国）

es-ES：西班牙语（西班牙）

fr-FR：法语（法国）

ja-JP：日语（日本）

ko-KR：韩语（韩国）

pt-PT：葡萄牙语（葡萄牙）

ru-RU：俄语（俄罗斯）

zh-CN：中文（中国）

zh-HK：中文（香港）

zh-TW：中文（台湾）

默认情况下，创建收银台时，我们会从请求到的收银台信息中获取语言，若没有符合的语言则会使用浏览器语言，若仍然不符合则使用 en-GB，如果您想固定展示某种语言，则可以在创建收银台的时候配置 locale。

欺诈检测

关于欺诈检测（FraudDetection）的配置，请参考 Fraud Detection SDK 使用文档。

如何使用组件

创建收银台实例后，您就可以创建组件了，举个例子，假设我们需要引入组件 A：

npm

CDN

调用收银台实例的 create 方法，传入组件所需参数 props 即可创建组件实例：

mount 方法支持传入 HTMLElement 对象或者 CSS 选择器字符串，并将组件实例渲染，挂载到真实dom中：

组件实例会提供 mount 方法用来将组件渲染到 DOM 上：

到此，组件就成功渲染到页面上了。

Card

Card 组件

示例

npm

CDN

API

CardProps

创建卡组件时传入。

必填参数用 * 标识

名称	说明	类型	默认值
showCardBrands	是否展示支持的发卡行 icon	`boolean`	`true`
onSubmit	表单提交回调，点击支付按钮后触发 `formValidateError` 为表单校验不通过的错误信息	`(formValidateError?: Record<string, FormValidateError[]>) => void`	`undefined`
onSuccess	点击支付按钮支付成功后的回调 `returnUrl` 为支付成功后需要跳转的 url	`(returnUrl: string) => void`	`undefined`
onError	支付失败后的回调	`(error: any) => void`	`undefined`
onTimeout	支付超时后的回调	`() => void`	`undefined`
onAuthorized	交易受到风控滞留后的回调	`() => void`	`undefined`
onExpired	会话过期或失效后的回调，或者支付成功后再次调起组件也会触发	`() => void`	`undefined`
onThreeDS	3DS 验证中的回调 `url` 为 3DS 验证链接 `incomplete` 为 `false` 表示为本次 3DS 验证中，为 `true` 表示上一次 3DS 验证中	`(url: string, incomplete: boolean) => void`	`undefined`

CardRef

卡组件实例暴露的方法和属性。

名称	说明	类型
payment	进行支付，在支付按钮配置为不可见时启用	`() => void`
checkThreeDS	进行支付结果查询	`() => void`

3DS

目前 Card 组件处理 3DS 时只会向外部发出回调，商户拿到 3DS 验证链接后需自行处理（如在页面弹窗中展示验证页面），验证完成后调用 checkThreeDS 方法进行支付结果查询：

Apple Pay

Apple Pay 组件

示例

npm

CDN

检测环境

我们在创建 Apple Pay 组件时会先引入 Apple Pay 官方提供的 SDK，您可以通过 onload 方法判断 SDK 是否加载成功：

如果您发现 SDK 加载成功，但页面上无法显示 Apple Pay 按钮，则可能是设备环境问题或其他原因导致无法支付，我们提供 onCanUse 回调方法告知您，具体不可见的原因可参考：Apple Pay 官方文档。

API

ApplePayProps

必填参数用 * 标识

名称	说明	类型	默认值
onLoad	SDK 加载回调，`status` 为 `true` 表示加载成功，`false` 表示加载失败	`(status: boolean) => void`	`undefined`
onSubmit	表单提交回调，点击支付按钮后触发 `formValidateError` 为表单校验不通过的错误信息	`(formValidateError?: Record<string, FormValidateError[]>) => void`	`undefined`
onSuccess	点击支付按钮支付成功后的回调 `returnUrl` 为支付成功后需要跳转的 url	`(returnUrl: string) => void`	`undefined`
onError	支付失败后的回调	`(error: any) => void`	`undefined`
onTimeout	支付超时后的回调	`() => void`	`undefined`
onAuthorized	交易受到风控滞留后的回调	`() => void`	`undefined`
onExpired	会话过期或失效后的回调，或者支付成功后再次调起组件也会触发	`() => void`	`undefined`
onCancel	支付取消	`() => void`	`undefined`
onCanUse	Apple Pay 是否可用	`(canUse: boolean) => void`	`undefined`

Google Pay

Google Pay 组件

示例

npm

CDN

检测环境

我们在创建 Google Pay 组件时会先引入 Google Pay 官方提供的 SDK，您可以通过 onload 方法判断 SDK 是否加载成功：

如果您发现 SDK 加载成功，但页面上无法显示 Google Pay 按钮，则可能是设备环境问题或其他原因导致无法支付，我们提供 onCanUse 回调方法告知您，具体不可见的原因可参考：Google Pay 官方文档。

API

GooglePayProps

必填参数用 * 标识

名称	说明	类型	默认值
onLoad	SDK 加载回调，`status` 为 `true` 表示加载成功，`false` 表示加载失败	`(status: boolean) => void`	`undefined`
onSubmit	表单提交回调，点击支付按钮后触发 `formValidateError` 为表单校验不通过的错误信息	`(formValidateError?: Record<string, FormValidateError[]>) => void`	`undefined`
onSuccess	点击支付按钮支付成功后的回调 `returnUrl` 为支付成功后需要跳转的 url	`(returnUrl: string) => void`	`undefined`
onError	支付失败后的回调	`(error: any) => void`	`undefined`
onTimeout	支付超时后的回调	`() => void`	`undefined`
onAuthorized	交易受到风控滞留后的回调	`() => void`	`undefined`
onExpired	会话过期或失效后的回调，或者支付成功后再次调起组件也会触发	`() => void`	`undefined`
onThreeDS	3DS 验证中的回调 `url` 为 3DS 验证链接 `incomplete` 为 `false` 表示为本次 3DS 验证中，为 `true` 表示上一次 3DS 验证中	`(url: string, incomplete: boolean) => void`	`undefined`
onCanUse	Google Pay 是否可用	`(canUse: boolean) => void`	`undefined`

错误处理

若在支付过程中遇到错误，组件会将后端返回的错误信息通过 onError 回调通知您，具体的错误码和描述参考：付款错误码

例子：

Sandbox 环境使用

如果您想在 sandbox 环境下接入 PayKKa 收银台，需要做一些特殊配置。

如果是 CDN 方式引入，需要引入 sandbox 环境的链接（npm 方式请忽略）：

创建收银台时将 sandbox 设置为 true 即可：

PayKKa Checkout UI Component 使用文档

安装#

npm#

CDN#

初始化#

hidePaymentButton#

locale#

欺诈检测#

如何使用组件#

Card#

示例#

API#

3DS#

Apple Pay#

示例#

检测环境#

API#

Google Pay#

示例#

检测环境#

API#

错误处理#

Sandbox 环境使用#

安装

npm

CDN

初始化

hidePaymentButton

locale

欺诈检测

如何使用组件

Card

示例

API

3DS

Apple Pay

示例

检测环境

API

Google Pay

示例

检测环境

API

错误处理

Sandbox 环境使用