Last Updated: 22 January 2024 | Change Log

Create sessionState - Advanced

Create a sessionState by sending your customer's card details.


A sessionState is a unique identifier for your customer's card details, which is generated by the SDK.

Full Integration example

See our GitHub repository for the full integration example.

Implementing callbacks

Our SDK uses callbacks to notify you when your customer's card details are valid or invalid. A sessionState can only be generated if your customer's card details are valid.


The CardListener is a callback that notifies you of the result of the validation of your customer's card details.

Here's an example of how you would implement the CardListener to check the validity of your customer's card details.

  1. Kotlin
  2. Java
 class YourCardListener: CardListener {

    override fun onUpdate(cardView: CardView, valid: Boolean) {
        // some logic can be added here, for example to determine whether to enable/disable your payment submit button
        // you may wish to use the `card.isValid()` method for determining whether the full card form is in a valid state

    override fun onUpdateLengthFilter(cardView: CardView, inputFilter: InputFilter) {

    override fun onUpdateCardBrand(cardBrand: CardBrand?) {
        // CardBrand contains a reference to a list of images which you can
        // use to fetch the remotely hosted image for the identified card brand.
        // do something with the card brand that is identified and returned
        // you may wish to use the `applyCardLogo()` method in the `PANLayout` class if you are using our fields out of the box.
Function and parameter Descriptions
onUpdateThis method returns the validity of a particular view that your customer is entering their details in.
The cardView represents the current view that your customer is in. valid indicates whether the field is in a valid or invalid state.
onUpdateLengthFilterThis method returns an updated maximum length restriction, which can be applied to the card view that your customer is entering their details in. This is based off the given card type that is identified.
onUpdateCardBrandThis method returns the card brand based on the details that your customer is entering. This method can be used to determine the logo of the card, which can be applied as a UI effect. If the card brand cannot be identified then a null response is returned.
The card brand will contain a list of images which you may then use to 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 views.

After implementing the CardListener callback, you must initialize the validation for your views.

  1. Kotlin
  2. Java
val card = AccessCheckoutCard(
    panView,            // The PAN view
    cardCVVText,        // The CVV view
    cardExpiryText      // The Expiry view

card.cardListener = this    // reference to `CardListener` implementation
card.cardValidator = AccessCheckoutCardValidator()  // reference to an AccessCheckoutCardValidator implementation

panView.cardViewListener = card
cardCVVText.cardViewListener = card
cardExpiryText.cardViewListener = card

Card validation callback

The validation logic, especially on the PAN and the CVV fields, in AccessCheckoutCard is based off a CardConfiguration JSON file, which holds the validation rules and card brand logos. The icons are available in both SVG and PNG.

Access Worldpay hosts a JSON based version of the card configuration file, which is available to consume via a CardConfigurationFactory. All that is required to set that up is:

  1. Kotlin
  2. Java
CardConfigurationFactory.getRemoteCardConfiguration(card, getBaseUrl())

You may use the supplied card configuration rules or supply your own rules based on your requirements.

  1. Kotlin
  2. Java
val cardConfiguration = CardConfiguration(brands = ..., defaults = ...)
card.cardValidator = AccessCheckoutCardValidator(cardConfiguration)

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

Validation Rules

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



You must also create a class that implements our SessionResponseListener.

The SessionResponseListener receives notifications during the lifecycle of the request. The SessionResponseListener is generates and returns the sessionState.

Here is an example of how you would create a class that implements our SessionResponseListener.

  1. Kotlin
  2. Java
class YourSessionResponseListener: SessionResponseListener {
    override fun onRequestStarted() {

    override fun onRequestFinished(sessionState: String?, error: AccessCheckoutException?) {

If there is an error, the error is returned by the SessionResponseListener through the onRequestFinished(sessionState: String?, error: AccessCheckoutException?) callback, this time with sessionState as null and error as a non-null error. See the table below for all the possible returned errors.

The following table of errors can be found in the enum class com.worldpay.access.checkout.api.AccessCheckoutException.Error

HTTP CodeError nameMessage
400bodyIsNotJsonThe body within the request is not valid JSON.
400bodyIsEmptyThe body within the request is empty.
400bodyDoesNotMatchSchemaThe JSON body provided does not match the expected schema.
404resourceNotFoundRequested resource was not found.
404endpointNotFoundRequested endpoint was not found.
405methodNotAllowedRequested method is not allowed.
406unsupportedAcceptHeaderAccept header is not supported.
415unsupportedContentTypeContent-type header is not supported.
500internalErrorOccurredInternal server error.
500unknownErrorUnknown error.

If you're presented with a bodyDoesNotMatchSchema error, a list of the broken validation rules is provided to help with debugging the problem.

AccessCheckoutClientError is the subclass used for the above issues.


data class AccessCheckoutClientError(
    val error: Error,
    override val message: String?,
    val validationRules: List<ValidationRule>? = null
) : AccessCheckoutException()

The validationRules list contains a list of ValidationRules, which includes the error, a description message and the JSON path to the location where the error was caused.

Initialize the SDK

Once you've created the classes and extended the callbacks, you must initialize the SDK using the AccessCheckoutClient method.

To initialize the SDK, you must provide your BaseURL, merchantID and other parameters. See the table below for more information.

Here's an example of how you would initialize the SDK with the parameters and configurations you must include.

  1. Kotlin
  2. Java
override fun onStart(){
    val accessCheckoutClient=AccessCheckoutClient.init(
    getBaseUrl(),           // Base API URL 
    getMerchantID(),        // Your merchant ID
    sessionResponseListener,// SessionResponseListener
    applicationContext,     // Context
    lifecycleOwner          // LifecycleOwner
  • For testing use :
  • For live use :
MerchantIDYour unique merchant ID.
sessionResponseListenerThe callback listener that returns your customer's sessionState.
applicationContextAndroid Context
lifecycleAndroid LifecycleOwner

Submitting your customer's card details

Once your customer has finished entering their card details and clicks the submit button, you must invoke the accessCheckoutClient.generateSessionState(...) method.

Here's an example of what you should do when your customer clicks the submit button.

  1. Kotlin
  2. Java
submit.setOnClickListener {
    val pan = panView.getInsertedText()
    val month = cardExpiryText.getMonth()
    val year = cardExpiryText.getYear()
    val cvv = cardCVVText.getInsertedText()
    accessCheckoutClient.generateSessionState(pan, month, year, cvv)

Generate sessionState

Generating the sessionState

The sessionState is returned in the response of the onRequestFinished() method, invoked inYourSessionResponseListener class.

  1. Kotlin
  2. Java
override fun onRequestFinished(sessionState: String?, error: AccessCheckoutException?) {

Create a Verified token

Once you've received a sessionState you must create a verified token to take a payment.

Next steps

Verified token