**Last updated**: 30 October 2025 | [**Change log**](/products/checkout/android/changelog/)

# 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](https://github.com/Worldpay/access-checkout-android/blob/v1.2.0/checkout/sample/src/main/java/com/worldpay/access/checkout/MainActivity.kt) 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.

Kotlin

```java
 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.
    }
 }
```

Java

```java
public class YourCardListener implements CardListener {

    @Override
    public void onUpdate(@NotNull CardView cardView, boolean valid) {
        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
    public void onUpdateLengthFilter(@NotNull CardView cardView, @NotNull InputFilter inputFilter) {
        cardView.applyLengthFilter(inputFilter)
    }

    @Override
    public void onUpdateCardBrand(@Nullable 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.
    }
}
```

details
summary
Function and parameter Descriptions
| Method | Description |
|  --- | --- |
| `onUpdate` | This 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. |
| `onUpdateLengthFilter` | This 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. |
| `onUpdateCardBrand` | This 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](https://access.worldpay.com/access-checkout/cardConfiguration.json) 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.

Kotlin

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

Java

```java
card = new AccessCheckoutCard(panView, cardCVVText, cardExpiryText);

card.setCardListener(yourCardListener);
card.setCardValidator(new AccessCheckoutCardValidator());

panView.setCardViewListener(card);
cardCVVText.setCardViewListener(card);
cardExpiryText.setCardViewListener(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](https://access.worldpay.com/access-checkout/cardConfiguration.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:

Kotlin

```java
CardConfigurationFactory.getRemoteCardConfiguration(card, getBaseUrl())
```

Java

```java
CardConfigurationFactory.getRemoteCardConfiguration(card, getBaseUrl());
```

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

Kotlin

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

Java

```java
CardConfiguration cardConfiguration = new CardConfiguration(..., ...);
card.setCardValidator(new AccessCheckoutCardValidator(cardConfiguration));
```

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

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

| Brand | `panStart` | `panEnd` | `panLength` | `cvvLength` |
|  --- | --- | --- | --- | --- |
| visa | 40 | 49 | 16 | 3 |
| visa | 413600 | 413600 | 13 | 3 |
| visa | 444509 | 444509 | 13 | 3 |
| visa | 444550 | 444550 | 13 | 3 |
| visa | 450603 | 450603 | 13 | 3 |
| visa | 450617 | 450617 | 13 | 3 |
| visa | 450628 | 450628 | 13 | 3 |
| visa | 450636 | 450636 | 13 | 3 |
| visa | 450640 | 450640 | 13 | 3 |
| visa | 450662 | 450662 | 13 | 3 |
| visa | 463100 | 463100 | 13 | 3 |
| visa | 476142 | 476142 | 13 | 3 |
| visa | 476143 | 476143 | 13 | 3 |
| visa | 492901 | 492901 | 13 | 3 |
| visa | 492920 | 492920 | 13 | 3 |
| visa | 492923 | 492923 | 13 | 3 |
| visa | 492928 | 492928 | 13 | 3 |
| visa | 492937 | 492937 | 13 | 3 |
| visa | 492939 | 492939 | 13 | 3 |
| visa | 492960 | 492960 | 13 | 3 |
| mastercard | 22 | 27 | 16 | 3 |
| mastercard | 50 | 59 | 16 | 3 |
| mastercard | 67 | 67 | 16 | 3 |
| amex | 34 | 34 | 15 | 4 |
| amex | 37 | 37 | 15 | 4 |


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

Kotlin

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

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

Java

```java
public class YourSessionResponseListener implements SessionResponseListener {
    @Override
    public void onRequestStarted() {
        ...
    }

    @Override
    public void onRequestFinished(@Nullable String sessionState, @Nullable AccessCheckoutException error) {
        ...
    }
}
```

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

#### Kotlin


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

The `validationRules` list contains a list of `ValidationRule`s, 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.

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
    )
    ...
}
```

Java

```java
@Override
protected void onStart(){
    super.onStart();
    ...
    AccessCheckoutClient 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](https://developer.android.com/reference/android/content/Context) |
| `lifecycle` | [Android LifecycleOwner](https://developer.android.com/reference/android/arch/lifecycle/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)
}
```

Java

```java
...
submit.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
      String pan = panView.getInsertedText();
      int month = cardExpiryText.getMonth();
      int year = cardExpiryText.getYear();
      String 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`](#sessionresponselistener) class.

Kotlin

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

Java

```java
...
@Override
public void onRequestFinished(@Nullable String sessionState, @Nullable AccessCheckoutException error) {
  ...
}
```

### Create a Verified token

Once you've received a `sessionState` you must create a [verified token](/products/verified-tokens/v2/create-verified-token#create-a-verified-token-request) to [take a payment](/products/card-payments/v6/authorize-a-payment#authorize-a-payment).

**Next steps**

[Verified token](/products/verified-tokens/v2/create-verified-token)