Menu

Card Validation

SDK v2
Last updated September 2021

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 create an implementation of a AccessCheckoutCardValidationListener. Initialize the validation using the AccessCheckoutValidationInitialiser by passing in the android UI elements in a CardValidationConfig.

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

Implementing AccessCheckoutCardValidationListener

To receive validation results of your customer's card details you are required to create your own implementation of the AccessCheckoutCardValidationListener

Copied!
package com.worldpay.access.checkout.sample.code

import com.worldpay.access.checkout.client.validation.listener.AccessCheckoutCardValidationListener
import com.worldpay.access.checkout.client.validation.model.CardBrand

class CardValidationListener : AccessCheckoutCardValidationListener {

    override fun onCvcValidated(isValid: Boolean) {
        //TODO: handle the cvc validation result
    }

    override fun onPanValidated(isValid: Boolean) {
        //TODO: handle the pan validation result
    }

    override fun onBrandChange(cardBrand : CardBrand?) {
        //TODO: handle the card brand change
    }

    override fun onExpiryDateValidated(isValid: Boolean) {
        //TODO: handle the expiry date validation result
    }

    override fun onValidationSuccess() {
        //TODO: handle the form when the validation is complete i.e. all fields are valid
    }

}
package com.worldpay.access.checkout.sample.code

import com.worldpay.access.checkout.client.validation.listener.AccessCheckoutCardValidationListener;
import com.worldpay.access.checkout.client.validation.model.CardBrand;

public class CardValidationListener implements AccessCheckoutCardValidationListener {

    @Override
    public void onCvcValidated(Boolean isValid) {
        //TODO: handle the cvc validation result
    }

    @Override
    public void onPanValidated(Boolean isValid) {
        //TODO: handle the pan validation result
    }

    @Override
    public void onBrandChange(CardBrand cardBrand) {
        //TODO: handle the card brand change
    }

    @Override
    public void onExpiryDateValidated(Boolean isValid) {
        //TODO: handle the expiry date validation result
    }

    @Override
    public void onValidationSuccess() {
        //TODO: handle the form when the validation is complete i.e. all fields are valid
    }

}

Initializing card validation

After implementing the AccessCheckoutCardValidationListener, you must initialize the validation for your views. To do this, first create a CardValidationConfig using the builder as shown below. Then use this to initialize the validation.

Copied!
package com.worldpay.access.checkout.sample.code

// android library imports omitted

import com.worldpay.access.checkout.client.validation.AccessCheckoutValidationInitialiser
import com.worldpay.access.checkout.client.validation.config.CardValidationConfig

class MainActivity : AppCompatActivity() {

    private val baseUrl = "TARGET_BASE_URL"

    // other fields omitted

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val pan = findViewById<EditText>(R.id.pan)
        val cvc = findViewById<EditText>(R.id.cvc)
        val expiryDate = findViewById<EditText>(R.id.expiryDate)

        // other view references omitted

        val cardValidationListener = CardValidationListener()

        val cardValidationConfig = CardValidationConfig.Builder()
                .baseUrl(baseUrl)
                .pan(pan)
                .expiryDate(expiryDate)
                .cvc(cvc)
                .validationListener(cardValidationListener)
                .lifecycleOwner(this)
                .build()

        AccessCheckoutValidationInitialiser.initialise(cardValidationConfig)

        //TODO: generate session here
    }

}
package com.worldpay.access.checkout.sample.code

// android library imports omitted

import com.worldpay.access.checkout.client.validation.AccessCheckoutValidationInitialiser;
import com.worldpay.access.checkout.client.validation.config.CardValidationConfig;
import com.worldpay.access.checkout.client.validation.listener.AccessCheckoutCardValidationListener;

public class MainActivity extends AppCompatActivity {

    private String baseUrl = "TARGET_BASE_URL";

    // other fields omitted

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        EditText pan = findViewById<EditText>(R.id.pan);
        EditText cvc = findViewById<EditText>(R.id.cvc);
        EditText expiryDate = findViewById<EditText>(R.id.expiryDate);

        // other view references omitted

        AccessCheckoutCardValidationListener cardValidationListener = CardValidationListener();

        CardValidationConfig cardValidationConfig = CardValidationConfig.Builder()
                .baseUrl(baseUrl)
                .pan(pan)
                .expiryDate(expiryDate)
                .cvc(cvc)
                .validationListener(cardValidationListener)
                .lifecycleOwner(this)
                .build();

        AccessCheckoutValidationInitialiser.initialise(cardValidationConfig);

        //TODO: generate session here
    }

}

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.

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!
val cardValidationConfig = CardValidationConfig.Builder()
        ...
        .acceptedCardBrands(arrayOf("visa", "mastercard", "amex"))
        ...
        .build()
CardValidationConfig cardValidationConfig = new CardValidationConfig.Builder()
        ...
        .acceptedCardBrands(new String[] {"visa", "mastercard", "amex"})
        ...
        .build();

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 call the enablePanFormatting method on the builder.

Copied!
val cardValidationConfig = CardValidationConfig.Builder()
        ...
        .enablePanFormatting()
        ...
        .build()
CardValidationConfig cardValidationConfig = new CardValidationConfig.Builder()
        ...
        .enablePanFormatting()
        ...
        .build();

Back toCARD session creationorCARD and CVC session creation.