Menu

Note: This SDK is for preview purposes only and is subject to change.

Card Validation

SDK v1
Coming soon

Validate your customer's card details before processing them.

Warning: The validation does not check if your customer's card details are correct. The validator only checks the formatting of the entered details.


Get started

To integrate the validation feature you must:

  • initialize the AccessCheckout client (you would already have an instance if you have implemented the Session feature)
  • create an implementation of a CardValidationEventListener to be notified of validation events
  • get an instance of the function used to initialize the validation, using our useCardValidation() hook
  • call that function once your UI components are present in the DOM in order to effectively initialize the validation

Full sample Integration: You can see an example of the card validation integrationhere.

Initialize the AccessCheckout client

First step to implement the validation is to create an instance of AccessCheckout, if you don't already have one.

To do this, you must provide your baseUrl and merchantId.

Here's an example of how to initialize it.

Copied!
import {
  AccessCheckout,
} from '@worldpay-beta/access-worldpay-checkout-react-native-sdk-beta';

const accessCheckout = new AccessCheckout({
  baseUrl: 'https://try.access.worldpay.com/',
  merchantId: 'YOUR_MERCHANT_ID',
});

Parameters

ParameterDescription
baseUrl
  • For testing use: https://try.access.worldpay.com/
  • For live use: https://access.worldpay.com/
merchantIdYour unique merchant ID.

Implement your CardValidationEventListener

To receive validation results of your customer's card details, you are required to create your own implementation of the CardValidationEventListener interface. Each of the function of this interface is optional to give you flexibility to listen to the events that you care about.

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-beta/access-worldpay-checkout-react-native-sdk-beta';

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
  },
};

Methods

MethodDescription
onCardBrandChangedThis method is called with a card brand based on the details that your customer is entering. The card brand contains a name as well as an array of images. If the card brand can't be identified, an undefined brand is passed to the method.
You may want to use thearray of imagesto display an icon for the identified card brand. Access Worldpay hosts both PNG and SVG versions of the supported card brands. You can use the icons right away and apply them to your UI.
onPanValidChangedThis method is called with the validity of the pan field. isValid indicates whether the field is in a valid or invalid state.
onExpiryDateValidChangedThis method is called with the validity of the expiry date field. isValid indicates whether the field is in a valid or invalid state.
onCvcValidChangedThis method is called with the validity of the CVC field. isValid indicates whether the field is in a valid or invalid state.
onValidationSuccessThis method is called when all fields are in a valid state. You typically use this to enable the submit button.

Call our hook to get the validation initialization function

You must now call our hook to get an instance of the function which will be used to initialize the validation of your UI.

To do this,

  1. create a CardValidationConfig to specify the id of the PAN, Expiry date and CVC TextInput.
  2. then call the useCardValidation() hook passing on the accessCheckout, the CardValidationConfig and your CardValidationEventListener implementation.

In result you will get an object with an initialiseCardValidation property containing the function to use to effectively initialize the validation.

Here is an example detailing how to do this.

Copied!
import {
  ...
  CardValidationConfig,
  useCardValidation,
} from '@worldpay-beta/access-worldpay-checkout-react-native-sdk-beta';

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

const { initialiseCardValidation } = useCardValidation(
  accessCheckout,
  validationConfig,
  validationEventListener
);

Initialize the validation

You can now initialize the validation using the initialiseCardValidation() function. Before doing so, you need to make sure that your UI components for PAN, Expiry Date and CVC are available in the DOM.

Validation initialization is an asynchronous process so make sure to handle the promise returned by the function.

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>
  ...

Card validation rules

The validation logic in the SDK, is based off a set of default rules for any card type. Specific brand rules are fetched from a CardTypes JSON file, which holds the validation rules and card brand logos for each brand. The icons are available in both SVG and PNG.

Validation rules

The table below shows the rules that our SDK uses to validate your customer's card details.

Card NameBIN RangePAN LengthCVC Length
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: optimized using 22 - 27163
Visa413, 16, 18, 193

Card brand restriction

The SDK enables you to optionally provide a list of card brands that you support. This means that if you do not support a certain card brand the SDK notifies your code of an invalid PAN if an unsupported brand is recognized.

By default, the SDK allows cards from any brand. If you do not wish to restrict the card brands that you accept then you do not need to pass any configuration.

Example configuration

To restrict the card brands that you accept, simply pass in an array of the brands that you do wish to accept when initializing the SDK.

The following validation configuration restricts the SDK to accept only American Express, Visa or Mastercard BIN ranges.

Copied!
const validationConfig = new CardValidationConfig({
  panId: 'panInput',
  expiryDateId: 'expiryDateInput',
  cvcId: 'cvcInput',
  acceptedCardBrands: ['visa', 'mastercard', 'amex'],
});

Currently supported card brands

The SDK is able to recognize the following card brands:

BrandCode
American Express"amex"
Diners"diners"
Discover"discover"
JCB"jcb"
Maestro"maestro"
Mastercard"mastercard"
Visa"visa"

If the SDK does not recognize a PAN as one of the above brands, it will be permitted as long as it meets the usual criteria for a valid PAN.

PAN formatting

The SDK allows PAN formatting as the customer types. This feature is disabled by default.

The PAN is formatted in the following way:

Card TypeFormatting
Visa, Mastercard, JCB, Discover, Diners, MaestroXXXX XXXX XXXX XXXX
AmexXXXX XXXXXX XXXXX

Enabling PAN formatting

To enable the PAN formatting behavior, simply pass true in the enablePanFormatting property of your CardValidationConfig.

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

Full code sample

Here's the full code sample of the steps above.

Copied!
import {
  AccessCheckout,
  CardValidationConfig,
  useCardValidation,
} from '@worldpay-beta/access-worldpay-checkout-react-native-sdk-beta';
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_MERCHANT_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-beta/access-worldpay-checkout-react-native-sdk-beta';
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_MERCHANT_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>
  );
}


Next steps


Create a session to pay with a cardor
Create sessions to pay with a card and cvc