Last Updated: 22 January 2024 | Change Log

Create `sessionState`

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

`SessionResponseListener`

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.

Kotlin
Java

class YourSessionResponseListener: SessionResponseListener {
    override fun onRequestStarted() {
        ...
    }
    
    override fun onRequestFinished(sessionState: String?, error: AccessCheckoutException?) {
        ....
    }
}

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 Code	Error name	Message
400	`bodyIsNotJson`	The body within the request is not valid JSON.
400	`bodyIsEmpty`	The body within the request is empty.
400	`bodyDoesNotMatchSchema`	The JSON body provided does not match the expected schema.
404	`resourceNotFound`	Requested resource was not found.
404	`endpointNotFound`	Requested endpoint was not found.
405	`methodNotAllowed`	Requested method is not allowed.
406	`unsupportedAcceptHeader`	Accept header is not supported.
415	`unsupportedContentType`	Content-type header is not supported.
500	`internalErrorOccurred`	Internal server error.
500	`unknownError`	Unknown 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.

Kotlin
Java

override fun onStart(){
    super.onStart()
    
    val accessCheckoutClient=AccessCheckoutClient.init(
        getBaseUrl(),           // Base API URL 
        getMerchantID(),        // Your merchant ID
        sessionResponseListener,// SessionResponseListener
        applicationContext,     // Context
        lifecycleOwner          // LifecycleOwner
    )
}

Methods	Descriptions
`BaseURL`	For testing use : `https://try.access.worldpay.com/` For live use : `https://access.worldpay.com/`
`MerchantID`	Your unique merchant ID.
`sessionResponseListener`	The callback listener that returns your customer's `sessionState`.
`applicationContext`	Android Context
`lifecycle`	Android 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.

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

Kotlin
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

Create sessionState

sessionState