注释:该 SDK 仅用于预览用途并会随时更改。
卡验证
在处理您客户的卡之前验证银行卡资料。
警告:该验证并不会检查客户的银行卡资料是否正确。验证器只会检查所输入的详情格式。
开始
若要集成验证功能,您必须:
- 初始化 AccessCheckout 客户端(如果您已实施会话功能,那么您便已经有了一个实例)
- 创建实施
CardValidationEventListener
,以通知验证事件 - 使用我们的
useCardValidation()
钩子,获取用于初始化验证的功能实例 - 您的 UI 组件出现在 DOM 中后,便调用该功能,以便有效初始化验证
完整示例集成:您可以在
初始化 AccessCheckout 客户端
实施验证的第一步是创建 AccessCheckout
的实例(如果您还没有实例的话)。
为此,您必须提供 baseUrl
和 merchantId
。
下方为如何进行初始化的示例。
import {
AccessCheckout,
} from '@worldpay/access-worldpay-checkout-react-native-sdk';
const accessCheckout = new AccessCheckout({
baseUrl: 'https://try.access.worldpay.com/',
merchantId: 'YOUR_CHECKOUT_ID',
});
参数
参数 | 描述 |
---|---|
baseUrl |
|
merchantId | 您独特的商户标识号。 |
实施您的 CardValidationEventListener
若要接收客户银行卡资料的验证结果,则您必须创建自己的 CardValidationEventListener
界面实施。 此界面的每个功能都是可选的,以使您能够灵活地听取所关注的事件。
const validationEventListener = {
onCardBrandChanged(brand) {
// TODO: handle the card brand change
// brand is an object properties name and images
// name contains the name of one of the brands supported and detected by the SDK
// images is an array of objects where each object has a type (image/png or image/svg+xml) and a url property
// brand will be undefined in the case where the PAN changes from a detected to an undetected card brand
},
onPanValidChanged(isValid) {
// TODO: handle the pan validation result
},
onExpiryDateValidChanged(isValid) {
// TODO: handle the expiry date validation result
},
onCvcValidChanged(isValid) {
// TODO: handle the cvc validation result
},
onValidationSuccess() {
// TODO: handle the form when the validation is complete i.e. all fields are valid
},
};
import {
...
Brand,
CardValidationEventListener,
} from '@worldpay/access-worldpay-checkout-react-native-sdk';
const validationEventListener: CardValidationEventListener = {
onCardBrandChanged(brand?: Brand): void {
// TODO: handle the card brand change
// brand is an object properties name and images
// name contains the name of one of the brands supported and detected by the SDK
// images is an array of objects where each object has a type (image/png or image/svg+xml) and a url property
// brand will be undefined in the case where the PAN changes from a detected to an undetected card brand
},
onPanValidChanged(isValid: boolean): void {
// TODO: handle the pan validation result
},
onExpiryDateValidChanged(isValid: boolean): void {
// TODO: handle the expiry date validation result
},
onCvcValidChanged(isValid: boolean): void {
// TODO: handle the cvc validation result
},
onValidationSuccess(): void {
// TODO: handle the form when the validation is complete i.e. all fields are valid
},
};
方法
方法 | 描述 |
---|---|
onCardBrandChanged | 该方法与基于您客户输入的资料的卡品牌一起调用。卡品牌包含 name 以及大量 images 。如果无法识别卡品牌,则系统会将 undefined 品牌传到该方法。您可能想要使用 |
onPanValidChanged | 该方法与 PAN 字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。 |
onExpiryDateValidChanged | 该方法与过期日期字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。 |
onCvcValidChanged | 该方法与 CVC 字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。 |
onValidationSuccess | 该方法在所有字段都处于有效状态时才调用。通常,您可以用它来启用提交按钮。 |
调用我们的钩子来获取验证初始化功能
您现在必须调用我们的钩子来获取功能的实例,该实例将用于初始化 UI 的验证。
要执行此操作,
- 创建
CardValidationConfig
,详细说明 PANid
、有效期和 CVCTextInput
。 - 然后调用传到
accessCheckout
上的useCardValidation()
钩子、CardValidationConfig
和您的CardValidationEventListener
实施。
因此,您将获得一个带有 initialiseCardValidation
属性的 object
,其中包含用于有效初始化验证的功能。
下方为详细说明如何执行此操作的示例。
import {
...
CardValidationConfig,
useCardValidation,
} from '@worldpay/access-worldpay-checkout-react-native-sdk';
const validationConfig = new CardValidationConfig({
panId: 'panInput',
expiryDateId: 'expiryDateInput',
cvcId: 'cvcInput',
});
const { initialiseCardValidation } = useCardValidation(
accessCheckout,
validationConfig,
validationEventListener
);
初始化验证
现在,您可以使用 initialiseCardValidation()
功能来初始化验证。 在执行此操作前,您需要确保您的 PAN、有效期和 CVC 的 UI 组件在 DOM 中可用。
验证初始化是一个异步的过程,因此请确保处理功能返回的承诺。
import React from 'react';
import { ..., View } from 'react-native';
...
<View
onLayout={() => {
initialiseCardValidation()
.then(() => {
// You may want to optionally perform some actions once validation has been successfully initialized.
})
.catch((error) => {
// do something in case of error
});
}}
>
...
</View>
...
卡验证规则
SDK 中的验证逻辑是基于任何卡类型的一套默认规则。具体品牌规则可从 CardTypes
JSON 文件中获取,其中包含了每个品牌的验证规则和卡品牌徽标。徽标分为 SVG
和 PNG
两种格式。
Validation rules
下表列出了我们的 SDK 用于验证您的客户银行卡资料的规则。
卡名称 | BIN 范围 | PAN 长度 | CVC 长度 |
---|---|---|---|
Amex | 34、37 | 15 | 4 |
Diners | 300 - 305、3095、36、38、39 | 14、16、19 | 3 |
Discover | 6011、644 - 649、65 | 16、19 | 3 |
JCB | 2131、1800、3088 - 3094、3096 - 3102、3112 - 3120、3158 - 3159、3337 - 3349、3528 - 3589 | 16、17、18、19 | 3 |
Maestro | 493698、500000 - 506698、506779- 508999、56 - 59、63、67、6 | 12、13、14、15、16、17、18、19 | 3 |
MasterCard | 51 - 55、2221 - 2229、223 - 229、23 - 26、270 - 271、2720:使用 22 - 27 | 16 | 3 优化 |
Visa | 4 | 13、16、18、19 | 3 |
卡品牌限制
SDK 让您能够视需要提供支持的卡品牌列表。也就是说,如果您不支持特定卡品牌,在识别到不支持的品牌时,SDK 会通知您无效的 PAN 代码。
默认情况下,SDK 允许任何品牌的卡。如果您不希望限制自己接受的卡,则不需要传送任何配置。
示例配置
若要限制您接受的卡品牌,只需传送在初始化 SDK 时您的确希望接受的品牌阵列即可。
以下验证配置可限制 SDK 只接受 American Express、Visa 或 Mastercard BIN 系列。
const validationConfig = new CardValidationConfig({
panId: 'panInput',
expiryDateId: 'expiryDateInput',
cvcId: 'cvcInput',
acceptedCardBrands: ['visa', 'mastercard', 'amex'],
});
当前支持的卡品牌
SDK 能够识别以下卡品牌:
品牌 | 代码 |
---|---|
American Express | "amex" |
Diners | "diners" |
Discover | "discover" |
JCB | "jcb" |
Maestro | "maestro" |
Mastercard | "mastercard" |
Visa | "visa" |
如果 SDK 无法识别作为上述品牌之一的 PAN,只要它符合有效 PAN 的一般标准,则也会被准许。
PAN formatting
SDK 允许根据客户类型进行 PAN 格式化。默认禁用此功能。
采用以下方式对 PAN 进行格式化:
银行卡类型 | 格式化 |
---|---|
Visa、Mastercard、JCB、Discover、Diners、Maestro | XXXX XXXX XXXX XXXX |
Amex | XXXX XXXXXX XXXXX |
启用 PAN 格式化
若要启用 PAN 格式化功能,只需在 CardValidationConfig
的 enablePanFormatting
属性中传递 True。
const validationConfig = new CardValidationConfig({
panId: 'panInput',
expiryDateId: 'expiryDateInput',
cvcId: 'cvcInput',
enablePanFormatting: true,
});
完整代码示例
以下是上述步骤的完整代码示例。
import {
AccessCheckout,
CardValidationConfig,
useCardValidation,
} from '@worldpay/access-worldpay-checkout-react-native-sdk';
import React from 'react';
import {TextInput, View} from 'react-native';
export default function CardFlow() {
const accessCheckout = new AccessCheckout({
baseUrl: 'https://try.access.worldpay.com/',
merchantId: 'YOUR_CHECKOUT_ID',
});
const validationEventListener = {
onCardBrandChanged(brand) {
// TODO: handle the card brand change
// brand is an object properties name and images
// name contains the name of one of the brands supported and detected by the SDK
// images is an array of objects where each object has a type (image/png or image/svg+xml) and a url property
// brand will be undefined in the case where the PAN changes from a detected to an undetected card brand
},
onPanValidChanged(isValid) {
// TODO: handle the pan validation result
},
onExpiryDateValidChanged(isValid) {
// TODO: handle the expiry date validation result
},
onCvcValidChanged(isValid) {
// TODO: handle the cvc validation result
},
onValidationSuccess() {
// TODO: handle the form when the validation is complete i.e. all fields are valid
},
};
const validationConfig = new CardValidationConfig({
panId: 'panInput',
expiryDateId: 'expiryDateInput',
cvcId: 'cvcInput',
});
const { initialiseCardValidation } = useCardValidation(
accessCheckout,
validationConfig,
validationEventListener,
);
return (
<View
onLayout={() => {
initialiseCardValidation()
.then(() => {
// You may want to optionally perform some actions once validation has been successfully initialized.
})
.catch((error) => {
// do something in case of error
});
}}
>
<TextInput
nativeID="panInput"
keyboardType="numeric"
placeholder="Card Number"
/>
<TextInput
nativeID="expiryDateInput"
keyboardType="numeric"
placeholder="MM/YY"
/>
<TextInput
nativeID="cvcInput"
keyboardType="numeric"
placeholder="CVC"
/>
</View>
);
}
import {
AccessCheckout,
Brand,
CardValidationConfig,
CardValidationEventListener,
useCardValidation,
} from '@worldpay/access-worldpay-checkout-react-native-sdk';
import React from 'react';
import { TextInput, View } from 'react-native';
export default function CardFlow() {
const accessCheckout = new AccessCheckout({
baseUrl: 'https://try.access.worldpay.com/',
merchantId: 'YOUR_CHECKOUT_ID',
});
const validationEventListener: CardValidationEventListener = {
onCardBrandChanged(brand?: Brand): void {
// TODO: handle the card brand change
// brand is an object properties name and images
// name contains the name of one of the brands supported and detected by the SDK
// images is an array of objects where each object has a type (image/png or image/svg+xml) and a url property
// brand will be undefined in the case where the PAN changes from a detected to an undetected card brand
},
onPanValidChanged(isValid: boolean): void {
// TODO: handle the pan validation result
},
onExpiryDateValidChanged(isValid: boolean): void {
// TODO: handle the expiry date validation result
},
onCvcValidChanged(isValid: boolean): void {
// TODO: handle the cvc validation result
},
onValidationSuccess(): void {
// TODO: handle the form when the validation is complete i.e. all fields are valid
},
};
const validationConfig = new CardValidationConfig({
panId: 'panInput',
expiryDateId: 'expiryDateInput',
cvcId: 'cvcInput',
});
const { initialiseCardValidation } = useCardValidation(
accessCheckout,
validationConfig,
validationEventListener
);
return (
<View
onLayout={() => {
initialiseCardValidation()
.then(() => {
// You may want to optionally perform some actions once validation has been successfully initialized.
})
.catch((error) => {
// do something in case of error
});
}}
>
<TextInput
nativeID="panInput"
keyboardType="numeric"
placeholder="Card Number"
/>
<TextInput
nativeID="expiryDateInput"
keyboardType="numeric"
placeholder="MM/YY"
/>
<TextInput
nativeID="cvcInput"
keyboardType="numeric"
placeholder="CVC"
/>
</View>
);
}
后续步骤