PayKKa Checkout UI 组件

如何工作

开始前准备

可以安装 PayKKa Checkout UI npm 包，或者通过 CDN 的方式嵌入到 HTML 中：

安装 @paykka/card-checkout-ui：

npm i @paykka/card-checkout-ui

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

import '@paykka/card-checkout-ui/style.css'

npm

安装 @paykka/card-checkout-ui：

npm i @paykka/card-checkout-ui

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

import '@paykka/card-checkout-ui/style.css'

CDN

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

<link href="https://checkout.eu.paykka.com/cp/style.css" rel="stylesheet" />
<script src="https://checkout.eu.paykka.com/cp/card-checkout-ui.js"></script>

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

// 获取需要使用的组件、方法
const { PayKKaCheckout, Card } = PayKKaCardCheckoutUI

初始化

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

import { PayKKaCheckout } from '@paykka/card-checkout-ui'
// 创建收银台实例
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'eu'
  // ...其他配置
})

强烈建议您不要在 iframe 元素内创建收银台，否则可能导致收银台无法正常使用。

初始化配置

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

必填参数用 * 标识

名称	说明	类型	默认值
*sessionId	收银台 ID，用来创建收银台	`string`	`undefined`
*clientKey	客户端密钥	`string`	`undefined`
*env	环境配置 `eu` 为欧洲商户 `hk` 为香港商户 `sandbox` 为沙箱环境商户	`eu \| hk \| sandbox`	`undefined`
locale	收银台文案展示语言不传则获取浏览器语言，若浏览器语言不在可支持语言列表，则默认使用 `en-GB`	`string`	浏览器语言 \| `en-GB`
hidePaymentButton	是否隐藏支付按钮若隐藏支付按钮，则需要手动调用组件的 `payment` 方法进行支付，用法参考	`boolean`	`false`
onPaymentMethodsReady	收银台已经获取可用支付方式时调用，返回可用支付方式若返回空数组，则表示无可用支付方式，且组件不会展示收银台状态为成功或过期时，同样会返回空数组	`(methods: PaymentMethod[]) => void`	`undefined`
onInitError	收银台初始化时报错触发 `error` 为错误信息收银台状态为成功或过期后再次初始化，同样会触发该回调	`(error: PayKKaError) => void`	`undefined`
threeDSFrame	定义 3DS 所需配置	`ThreeDSFrameConfig`	`undefined`

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

自定义支付按钮

hidePaymentButton 用来配置是否隐藏 PayKKa 内置的支付按钮。

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

下面用 Card 组件举个例子：

html

<button onclick="handleClickPayment()">支付</button>

javascript

// 假设我们已经初始化收银台并把 hidePaymentButton 设置为 true
import { Card } from '@paykka/card-checkout-ui'

// 创建 Card 组件
const CheckoutCard = paykkaCheckout.create(Card, {
  // card 配置
})

const handleClickPayment = () => {
  // 点击支付按钮后，调用 payment 方法进行支付
  CheckoutCard.ref.payment()
}

语言

目前 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。

支付方式

目前 PayKKa Checkout UI 支持如下 8 种支付方式：

APPLE_PAY：Apple Pay
GOOGLE_PAY：Google Pay
VISA：Visa
MASTER_CARD：Master Card
JCB：JCB
AMEX：AMEX
DINERS_CLUB：Diners Club
DISCOVER：Discover

3DS 配置

您可以在初始化时定义部分 3DS 配置，目前包含以下配置项：

interface ThreeDSFrameConfig {
  /** 3DS 弹窗宽度，不传默认自适应。传 number 单位为 px， 传 string 可自定义单位，最小宽度为 350px */
  modalWidth?: number | string
  /** 3DS 弹窗高度，不传默认自适应。传 number 单位为 px， 传 string 可自定义单位，最小高度为 500px */
  modalHeight?: number | string
}

欺诈检测

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

错误信息

收银台的所有错误都会已 PayKKaError 实例的形式抛出，通常包含以下属性：

type: 错误类型
message: 错误信息
code: 错误码，在发生接口错误时，会返回具体的错误码

如何使用组件

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

import { Card } from '@paykka/card-checkout-ui'

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

const props = {
  // card props
}

// 调用收银台实例的 create 方法
const InstCard = paykkaCheckout.create(Card, props)

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

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

<div id="Card"></div>

// 传入 HTMLElement
const container = document.querySelector('#Card')
InstCard.mount(container)

// or

// 传入 CSS 选择器字符串
InstCard.mount('#Card')

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

Sandbox 环境使用

如果您想在 sandbox 环境下接入收银台，可按照如下步骤处理。

如果是 CDN 方式引入，需要引入 sandbox 环境的链接（npm 方式请到下一步）：

<link
  href="https://checkout-sandbox.aq.paykka.com/cp/style.css"
  rel="stylesheet"
/>
<script src="https://checkout-sandbox.aq.paykka.com/cp/card-checkout-ui.js"></script>

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

const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'sandbox'
  // ...other options
})