Last Updated: 22 January 2024 | Change Log

Create sessionState - Advanced

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

sessionState

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.

CardListener

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.

 class YourCardListener: CardListener {

    override fun onUpdate(cardView: CardView, valid: Boolean) {
        cardView.isValid(valid)
        // 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) {
        cardView.applyLengthFilter(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.
    }
 }

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

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:

CardConfigurationFactory.getRemoteCardConfiguration(card, getBaseUrl())

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

val cardConfiguration = CardConfiguration(brands = ..., defaults = ...)
card.cardValidator = AccessCheckoutCardValidator(cardConfiguration)

SessionResponseListener

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.

class YourSessionResponseListener: SessionResponseListener {
    override fun onRequestStarted() {
       ...
    }

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

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

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.

override fun onStart(){
    super.onStart()
    val accessCheckoutClient=AccessCheckoutClient.init(
    getBaseUrl(),           // Base API URL 
    getMerchantID(),        // Your merchant ID
    sessionResponseListener,// SessionResponseListener
    applicationContext,     // Context
    lifecycleOwner          // 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.

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

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