Last Updated: 22 January 2024 | Change Log

Create sessionState

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 have been converted into a sessionState.


You must create a class that implements our SessionResponseListener.

The SessionResponseListener receives notifications during the lifecycle of the request. The SessionResponseListener 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.

data class ValidationRule(val errorName: ValidationRuleName, val message: String, val jsonPath: String)

Initialize the SDK

Once you've created the class and extended the callback, 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 in YourSessionResponseListener 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