> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/additional-features/add-wallet-transaction-data.md).

# Add wallet transaction data

## Overview

You can attach wallet transaction data to a contactless payment. The processing host can use this data during authorization processing.

Wallet transaction data is defined for each digital card. You can provide it in two ways:

* **Persistent:** The SDK stores the data in secure storage. It remains available after the digital wallet application restarts.
* **Ephemeral:** The digital wallet application provides the data for one transaction only.

The digital wallet application decides whether to include this data in each payment.

This feature is supported for Mastercard (MCBP 2.3) and PURE contactless payment profiles.

Before a transaction, the wallet transaction data mode must be set to specify whether to use stored persistent data or ephemeral custom data.

The wallet transaction data mode resets after each transaction and must be re-established if the card changes during a transaction.

{% hint style="warning" %}
The following APIs are deprecated as of `6.14.0`:

* `DigitalizedCard.setWalletTransactionData(WalletTransactionData walletTransactionData)`
* `DigitalizedCard.getWalletTransactionData()`
* `PaymentBusinessService.setWalletTransactionData(WalletTransactionData walletTransactionData)`

Use the APIs introduced in `6.14.0` for new integrations.
{% endhint %}

### Supported profiles

#### Mastercard (MCBP 2.3)

NFC Wallet SDK supports Mastercard specification **MCBP 2.3**.

If wallet transaction data is available before a contactless transaction, the SDK updates the `IAD` (EMV tag `9F10`, Issuer Application Data):

* Start offset: byte 19
* Max IAD length: 32 bytes
* Maximum wallet transaction data length: 14 bytes

In MCBP 2.3, this feature is called **wallet proprietary information**.

#### PURE contactless

If wallet transaction data is available before a contactless transaction, the SDK updates the `IAD` (EMV tag `9F10`, Issuer Application Data):

* Start offset: byte 18
* Max IAD length: 32 bytes
* Maximum wallet transaction data length: 15 bytes

## SDK integration

### Set wallet transaction data mode

Set the wallet transaction data mode before the transaction starts.

Use `PaymentBusinessService.setWalletTransactionDataMode(WalletTransactionDataMode)` to select how the SDK supplies wallet transaction data for the next payment.

Available modes:

* **Storage mode:** Use the default wallet transaction data stored for the digital card.
* **Ephemeral mode:** Set a wallet transaction data for the next transaction only. This data will not be stored.

{% hint style="warning" %}
Wallet transaction data mode is reset:

* on card change during a transaction. See [Handle a card change during a transaction](#handle-a-card-change-during-a-transaction).
* after the transaction, regardless of status (success, failure, or cancellation)
  {% endhint %}

#### Use storage mode

In the code snipet below the digital wallet application notifies the NFC Wallet SDK to use the persistent wallet transaction data for the next transaction.

{% code lineNumbers="true" %}

```java
// Set default wallet transaction data for a payment transaction.
PaymentBusinessManager.getPaymentBusinessService().
setWalletTransactionDataMode(WalletTransactionDataMode.storage());
```

{% endcode %}

{% hint style="info" %}
See [Manage persistent wallet transaction data](#manage-persistent-wallet-transaction-data) for details on setting persistent wallet transaction data for each digital card.
{% endhint %}

#### Use ephemeral mode

In the code snipet below the digital wallet application is providing to the NFC Wallet SDK the ephemeral wallet transaction data for the next transaction.

For Mastercard, the payload can contain up to 14 bytes. For PURE, it can contain up to 15 bytes.

{% code overflow="wrap" lineNumbers="true" %}

```java
// Set custom wallet transaction data for a payment transaction.
byte[] walletTransactionData = new byte[]{(byte) 0x0a, (byte) 0x0c, (byte) 0x0f, (byte) 0x0d, (byte) 0xae, (byte) 0xdd, (byte) 0xee, (byte) 0xaa};

PaymentBusinessManager.getPaymentBusinessService().
setWalletTransactionDataMode(WalletTransactionDataMode.ephemeral(walletTransactionData));
```

{% endcode %}

{% hint style="info" %}
NFC Wallet SDK pads PURE wallet transaction data with `00` bytes when needed to reach 15 bytes.\
NFC Wallet SDK does not pad Mastercard wallet transaction data.
{% endhint %}

### Manage persistent wallet transaction data

Stored wallet transaction data is associated with a digital card. The SDK uses this value if you select the **storage mode**.

#### Set persistent wallet transaction data

Use `DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData)` to set persistent wallet transaction data.

* Pass up to 14-byte `byte[]` for Mastercard 2.3.
* Pass up to 15-byte `byte[]` for PURE.

{% code lineNumbers="true" expandable="true" %}

```java
String tokenId = "tokenId";
DigitalizedCard digitalizedCard = DigitalizedCardManager.getDigitalizedCard(tokenId);

// Wallet transaction data to set (14 bytes as per Mastercard)
byte[] walletTransactionDataToSet = new byte[]{
    (byte) 0xaa, (byte) 0xba, (byte) 0xca, (byte) 0xda,
    (byte) 0xea, (byte) 0xfa, (byte) 0xff, (byte) 0xaa,
    (byte) 0xba, (byte) 0xca, (byte) 0xda, (byte) 0xea,
    (byte) 0xfa, (byte) 0xff
};

try {
    // Set the wallet transaction data on the card
    digitalizedCard.setWalletTransactionData(walletTransactionDataToSet);
    
    // ... App logic here .

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}
```

{% endcode %}

{% hint style="info" %}
NFC Wallet SDK pads PURE wallet transaction data with `00` bytes when needed to reach 15 bytes.\
NFC Wallet SDK does not pad Mastercard wallet transaction data.
{% endhint %}

#### Clear persistent wallet transaction data

Use `DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData)` and pass `null` to clear the stored value for the digital card

{% code lineNumbers="true" expandable="true" %}

```java
String tokenId = "tokenId";
DigitalizedCard digitalizedCard = DigitalizedCardManager.getDigitalizedCard(tokenId);

try {
    // Clear the persistent wallet transaction data
    digitalizedCard.setWalletTransactionData(null);

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}
```

{% endcode %}

#### Retrieve persistent wallet transaction data

Use `DigitalizedCard.retrieveWalletTransactionData()` to retrieve the wallet transaction data associated with the digital card.

{% code lineNumbers="true" expandable="true" %}

```java
String tokenId = "tokenId";
DigitalizedCard digitalizedCard = DigitalizedCardManager.getDigitalizedCard(tokenId);

try {
    // Retrieve the wallet transaction data from the card
    byte[] retrievedWalletTransactionData = digitalizedCard.retrieveWalletTransactionData();
    if (retrievedWalletTransactionData != null) {
        // Process the retrieved data here
    } else {
        // No wallet transaction data found 
    }

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}
```

{% endcode %}

### Handle a card change during a transaction

If the card changes during the transaction, the **digital wallet application** must set the wallet transaction data mode again after a successful card activation callback.

{% code lineNumbers="true" %}

```java
final PaymentBusinessService paymentBusinessService = PaymentBusinessManager.getPaymentBusinessService();
CardActivationListener activationListener = new CardActivationListener() {
  @Override
  public void onCardActivated(PaymentServiceErrorCode code) {
    if (code == PaymentServiceErrorCode.SUCCESS) {
      try {
        PaymentBusinessManager.getPaymentBusinessService()
            .setWalletTransactionDataMode(WalletTransactionDataMode.storage());
      } catch (InternalComponentException e) {
        // Handle exceptions.
      }
    }
  }
};

// Start a payment with a different card.
paymentBusinessService.activateNonDefaultCard(
    cardBTokenId,
    PaymentType.CONTACTLESS,
    keepAsDefault,
    paymentServiceListener,
    activationListener
);
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/additional-features/add-wallet-transaction-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.