> 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-ios/additional-features/add-wallet-transaction-data.md).

# Add wallet transaction data

## Overview

You can attach wallet transaction data to a contactless payment.

The issuer backend can use this data during authorization processing.

Wallet transaction data is defined per digital card.

The digital wallet application can provide it in two modes:

* **Persistent**: The NFC Wallet SDK stores the data in secure storage. It persists across application restarts.
* **Ephemeral**: The digital wallet application provides the value for one transaction only.

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

{% hint style="info" %}
The NFC Wallet SDK supports wallet transaction data for Mastercard and PURE contactless profiles only.
{% endhint %}

### Mastercard specification (MCBP 2.3)

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

If wallet transaction data is available before a contactless transaction, the NFC Wallet 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

{% hint style="info" %}
In MCBP 2.3, this feature is named **wallet proprietary information**.
{% endhint %}

### PURE specification

The NFC Wallet SDK also supports wallet transaction data for PURE contactless profiles.

If wallet transaction data is available before a contactless transaction, the NFC Wallet 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 persistent wallet transaction data for Mastercard

Use `DigitalCard.setWalletTransactionData` to set persistent wallet transaction data:

* Pass a 14-byte `Data` value to store wallet transaction data for this digital card.
* Pass `nil` to clear the stored value for this digital card.

```swift
do {      
    // Set wallet transaction data for Mastercard, data length = 14 bytes.
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Clear wallet transaction data for this card
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Handle the error  
}
```

### Set persistent wallet transaction data for PURE

Use `DigitalCard.setWalletTransactionData` to set persistent wallet transaction data:

* Pass a 15-byte `Data` value to store wallet transaction data for this digital card.
* Pass `nil` to clear the stored value for this digital card.

```swift
do {      
    // Set wallet transaction data for this specific card
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Clear wallet transaction data for this card
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Handle the error  
}
```

### Handle errors

The wallet transaction data must meet the following requirements:

* Length for Mastercard: Exactly 14 bytes
* Length for PURE: Exactly 15 bytes
* Scheme support: Only Mastercard and PURE contactless profiles are supported. If you set wallet transaction data for another scheme, the SDK returns `.schemeNotSupported`.

```swift
do {
      try await digitalCard.setWalletTransactionData(data)
  } catch DigitalCard.Error.invalidWalletTransactionData {
      // Scheme based length validation.
      // For Mastercard, the data length is not 14 bytes. 
      // For PURE card, the data length is not 15 bytes. 
  } catch DigitalCard.Error.schemeNotSupported {
      // Card scheme does not support wallet transaction data (e.g., Visa)
  } catch {
      // Other errors
  }
```

### Provide wallet transaction data for a payment

Use `startPayment()` with `ContactlessPaymentInputData` to provide wallet transaction data during a contactless payment.

`ContactlessPaymentInputData` supports two wallet transaction data modes:

* `.storage`: Use the value stored in secure storage (if set).
* `.ephemeral`: Provide a value for this transaction only.

#### Storage mode

```swift
let paymentInputData = ContactlessPaymentInputData(
    digitalCardID: card.id,
    walletTransactionDataMode: .storage
)
```

#### Ephemeral mode

```swift
let paymentInputData = ContactlessPaymentInputData(
    digitalCardID: card.id,
    walletTransactionDataMode: .ephemeral(customData)
)
```

#### Start a payment

```swift
// start payment with provided contactlessPaymentInputData
// use case: manual mode (with user interaction)
await session.startPayment(with contactlessPaymentInputData: contactlessPaymentInputData)
```


---

# 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:

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

The question should be specific, self-contained, and written in natural language.
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.