Translation disclaimer

Documentation is written in English and subsequently translated. This page, therefore, might not have the most up-to-date content. If any questions arise relating to the accuracy of the translated content, please refer to the English version of the page.

Menu

注释:该 SDK 仅用于预览用途并会随时更改。

卡验证

在处理您客户的卡之前验证银行卡资料。

警告:该验证并不会检查客户的银行卡资料是否正确。验证器只会检查所输入的详情格式。


开始

若要集成验证功能,您必须:

  • 初始化 AccessCheckout 客户端(如果您已实施会话功能,那么您便已经有了一个实例)
  • 创建实施 CardValidationEventListener,以通知验证事件
  • 使用我们的 useCardValidation() 钩子,获取用于初始化验证的功能实例
  • 您的 UI 组件出现在 DOM 中后,便调用该功能,以便有效初始化验证

完整示例集成:您可以在此处查看卡验证集成的示例。

初始化 AccessCheckout 客户端

实施验证的第一步是创建 AccessCheckout 的实例(如果您还没有实例的话)。

为此,您必须提供 baseUrlmerchantId

下方为如何进行初始化的示例。

Copied!
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
  • 对于测试用途:https://try.access.worldpay.com/
  • 对于实时用途:https://access.worldpay.com/
merchantId您独特的商户标识号。

实施您的 CardValidationEventListener

若要接收客户银行卡资料的验证结果,则您必须创建自己的 CardValidationEventListener 界面实施。 此界面的每个功能都是可选的,以使您能够灵活地听取所关注的事件。

Copied!
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 品牌传到该方法。
您可能想要使用大量图像来显示标识卡品牌的图标。Access Worldpay 可同时托管支持的卡品牌的 PNG 和 SVG 版本。您可以立即使用这些图标并将它们应用于您的 UI。
onPanValidChanged该方法与 PAN 字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。
onExpiryDateValidChanged该方法与过期日期字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。
onCvcValidChanged该方法与 CVC 字段的有效性一起调用。 isValid 表示该字段是处于有效还是无效状态。
onValidationSuccess该方法在所有字段都处于有效状态时才调用。通常,您可以用它来启用提交按钮。

调用我们的钩子来获取验证初始化功能

您现在必须调用我们的钩子来获取功能的实例,该实例将用于初始化 UI 的验证。

要执行此操作,

  1. 创建 CardValidationConfig,详细说明 PAN id、有效期和 CVC TextInput
  2. 然后调用传到 accessCheckout 上的 useCardValidation() 钩子、CardValidationConfig 和您的 CardValidationEventListener 实施。

因此,您将获得一个带有 initialiseCardValidation 属性的 object,其中包含用于有效初始化验证的功能。

下方为详细说明如何执行此操作的示例。

Copied!
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 中可用。

验证初始化是一个异步的过程,因此请确保处理功能返回的承诺。

Copied!
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 文件中获取,其中包含了每个品牌的验证规则和卡品牌徽标。徽标分为 SVGPNG 两种格式。

Validation rules

下表列出了我们的 SDK 用于验证您的客户银行卡资料的规则。

卡名称BIN 范围PAN 长度CVC 长度
Amex34、37154
Diners300 - 305、3095、36、38、3914、16、193
Discover6011、644 - 649、6516、193
JCB2131、1800、3088 - 3094、3096 - 3102、3112 - 3120、3158 - 3159、3337 - 3349、3528 - 358916、17、18、193
Maestro493698、500000 - 506698、506779- 508999、56 - 59、63、67、612、13、14、15、16、17、18、193
MasterCard51 - 55、2221 - 2229、223 - 229、23 - 26、270 - 271、2720:使用 22 - 27163 优化
Visa413、16、18、193

卡品牌限制

SDK 让您能够视需要提供支持的卡品牌列表。也就是说,如果您不支持特定卡品牌,在识别到不支持的品牌时,SDK 会通知您无效的 PAN 代码。

默认情况下,SDK 允许任何品牌的卡。如果您不希望限制自己接受的卡,则不需要传送任何配置。

示例配置

若要限制您接受的卡品牌,只需传送在初始化 SDK 时您的确希望接受的品牌阵列即可。

以下验证配置可限制 SDK 只接受 American Express、Visa 或 Mastercard BIN 系列。

Copied!
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、MaestroXXXX XXXX XXXX XXXX
AmexXXXX XXXXXX XXXXX

启用 PAN 格式化

若要启用 PAN 格式化功能,只需在 CardValidationConfigenablePanFormatting 属性中传递 True。

Copied!
const validationConfig = new CardValidationConfig({
  panId: 'panInput',
  expiryDateId: 'expiryDateInput',
  cvcId: 'cvcInput',
  enablePanFormatting: true,
});

完整代码示例

以下是上述步骤的完整代码示例。

Copied!
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>
  );
}


后续步骤


创建会话以便使用卡进行支付,或
创建会话以便使用卡和 CVC 进行支付