Encrypted Card 使用

介绍

Encrypted Card 用于收集并加密卡号、过期时间和 CVV 信息。如果您使用自定义支付表单并希望符合 PCI 标准，建议采用 Encrypted Card。

该方式基于支付 API，接入前需完成商户身份校验，请确认以下条件：

已注册商户并获取有效客户端密钥（clientKey）。

能够自行调用我们的支付 API。

引入

Encrypted Card 支持 npm 和 CDN 两种方式引入：

npm

CDN

下载最新版本的 @paykka/card-checkout-ui：

导入 PayKKaEncryptedCard ：

使用

布局

Encrypted Card 的表单域支持分开和合并两种展示方式，您需要在 HTML 中预先定义好。

注意

Encrypted Card 会根据元素的 id 和 data-eci 属性将表单域插入到指定位置，请务必对元素设置正确的属性名和值。

多个：

单个：

调用 init 方法进行初始化，如 PayKKaEncryptedCard.init({ // ...配置 })，初始化时可配置项如下：

必填参数用 * 标识

属性	描述	类型
*merchantId	商户 ID	`string`
*clientKey	客户端密钥	`string`
locale	表单项所展示的语言	`LocaleKeyType`
brands	有效的卡品牌数组身份验证完成后会获取商户可用卡品牌，然后两者取交集如果不传，则直接取商户可用卡品牌	`CardBrand[]`
styles	输入框、label 和错误提示文字的样式	`ElementStylesConfig`
showLabel	是否展示 label，默认为 `true`	`boolean`
sandbox	是否使用 sandbox 环境	`boolean`

可以通过回调监听 Encrypted Card 发出的事件：

事件	描述	类型
onReady	身份校验完成后调用，并返回校验结果，若校验成功则返回可用卡品牌	`(status: boolean, res?: { brands: CardBrand[] }) => void`
onActivated	表单域渲染完成后触发，并返回对应表单域类型	`(fieldType: FieldType) => void`
onFocus	表单域获得焦点时触发，并返回对应表单域类型	`(fieldType: FieldType) => void`
onBlur	表单域失去焦点时触发，并返回对应表单域类型	`(fieldType: FieldType) => void`
onBinChanged	卡 bin 信息改变时触发返回包含卡号前 1-6 位的值和卡品牌如果用户删除卡号，或卡号不足 6 位，则 `binValue` 为空	`(binInfo: { binValue: string; brand?: CardBrand }) => void`
onBrand	检测到卡品牌时调用，返回对应卡品牌	`(brand?: CardBrand) => void`
onCardEncrypted	卡信息加密成功后触发，返回加密结果	`(encryptedInfo: EncryptCardRes) => void`
onCardEncryptionFailed	卡信息加密失败后触发	`() => void`
onValidationChanged	通知表单项验证信息返回对应表单域类型和验证状态	`(validationInfo: { fieldType: FieldType; status: FormValidationStatus) }) => void`

Encrypted Card 初始化之后会暴露以下 API：

属性	描述	类型
encrypt	调用该方法开始表单验证和加密流程	`() => void`

详细说明

语言

LocaleKeyType

目前我们支持如下 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：中文（台湾）

默认情况下，Encrypted Card 会使用浏览器语言，若仍然不符合则使用 en-GB，如果您想固定展示某种语言，则可以在初始化时配置 locale。

卡品牌

CardBrand

目前我们支持的卡品牌枚举和对应卡品牌如下：

样式

ElementStylesConfig

样式对象类型如下，您可以自定义输入框、label 和错误提示文案下对应状态的样式，CSSStyleDeclaration 表示我们支持绝大部分的样式：

表单域类型

FieldType

表单类型枚举及对应描述如下:

加密结果

EncryptCardRes

加密结果类型定义如下：

验证状态

FormValidationStatus

表单验证状态分为三种，状态值和对应描述如下：

unValidate: 内容为空

success: 校验成功

error: 校验失败

示例

下面是从初始化表单域到完成加密的代码示例：

Sandbox 环境接入

Sandbox 环境下接入，需要引入 Sandbox 环境的 CDN，并在初始化时设置 sandbox 为 true。

介绍#

引入#

使用#

布局#

详细说明#

语言#

卡品牌#

样式#

表单域类型#

加密结果#

验证状态#

示例#

Sandbox 环境接入#

介绍

引入

使用

布局

详细说明

语言

卡品牌

样式

表单域类型

加密结果

验证状态

示例

Sandbox 环境接入