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

# ウォレットのトランザクションデータを追加する

## 概要

ウォレット取引データを非接触決済に添付できます。処理ホストは、認証処理中にこのデータを使用できます。

ウォレット取引データは各デジタルカードごとに定義されます。次の2つの方法で提供できます。

* **永続:** SDK はデータを安全なストレージに保存します。デジタルウォレットアプリケーションが再起動しても利用可能なままです。
* **一時的:** デジタルウォレットアプリケーションは、1回の取引に対してのみデータを提供します。

デジタルウォレットアプリケーションは、各決済にこのデータを含めるかどうかを決定します。

この機能は、Mastercard (MCBP 2.3) および PURE の非接触決済プロファイルでサポートされています。

取引の前に、保存済みの永続データを使用するか、一時的なカスタムデータを使用するかを指定するため、ウォレット取引データモードを設定する必要があります。

ウォレット取引データモードは各取引後にリセットされ、取引中にカードが変更された場合は再設定する必要があります。

{% hint style="warning" %}
次の API は、以下の時点で非推奨です `6.14.0`:

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

新しい統合では、以下で導入された API を使用してください `6.14.0` 。
{% endhint %}

### サポートされるプロファイル

#### Mastercard (MCBP 2.3)

NFC Wallet SDK は Mastercard 仕様をサポートしています **MCBP 2.3**.

非接触取引の前にウォレット取引データが利用可能な場合、SDK は次の項目を更新します `IAD` (EMV タグ `9F10`、Issuer Application Data):

* 開始オフセット: 19 バイト目
* 最大 IAD 長: 32 バイト
* 最大ウォレット取引データ長: 14 バイト

MCBP 2.3 では、この機能は次のように呼ばれます **ウォレット専有情報**.

#### PURE 非接触

非接触取引の前にウォレット取引データが利用可能な場合、SDK は次の項目を更新します `IAD` (EMV タグ `9F10`、Issuer Application Data):

* 開始オフセット: 18 バイト目
* 最大 IAD 長: 32 バイト
* 最大ウォレット取引データ長: 15 バイト

## SDK 統合

### ウォレット取引データモードを設定する

取引が開始される前に、ウォレット取引データモードを設定します。

使用します `PaymentBusinessService.setWalletTransactionDataMode(WalletTransactionDataMode)` SDK が次の決済に対してウォレット取引データをどのように提供するかを選択するために使用します。

利用可能なモード:

* **ストレージモード:** デジタルカード用に保存されたデフォルトのウォレット取引データを使用します。
* **一時モード:** 次の取引に対してのみウォレット取引データを設定します。このデータは保存されません。

{% hint style="warning" %}
ウォレット取引データモードは次の場合にリセットされます:

* 取引中のカード変更時。参照してください [取引中のカード変更を処理する](#handle-a-card-change-during-a-transaction).
* 取引後、ステータスに関係なく（成功、失敗、またはキャンセル）
  {% endhint %}

#### ストレージモードを使用する

以下のコードスニペットでは、デジタルウォレットアプリケーションが NFC Wallet SDK に対して、次の取引で永続ウォレット取引データを使用するよう通知しています。

{% code lineNumbers="true" %}

```java
// 支払い取引のデフォルトのウォレット取引データを設定します。
PaymentBusinessManager.getPaymentBusinessService().
setWalletTransactionDataMode(WalletTransactionDataMode.storage());
```

{% endcode %}

{% hint style="info" %}
参照 [永続ウォレット取引データを管理する](#manage-persistent-wallet-transaction-data) 各デジタルカードの永続ウォレット取引データの設定の詳細については、こちらを参照してください。
{% endhint %}

#### 一時モードを使用する

以下のコードスニペットでは、デジタルウォレットアプリケーションが NFC Wallet SDK に対して、次の取引用の一時ウォレット取引データを提供しています。

Mastercard では、ペイロードは最大 14 バイトを含めることができます。PURE では、最大 15 バイトを含めることができます。

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

```java
// 支払い取引のカスタムウォレット取引データを設定します。
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 は、必要に応じて PURE のウォレット取引データを `00` バイトで埋め、15 バイトに達するようにします。\
NFC Wallet SDK は Mastercard のウォレット取引データを埋めません。
{% endhint %}

### 永続ウォレット取引データを管理する

保存されたウォレット取引データはデジタルカードに関連付けられています。SDK は、 **ストレージモード**.

#### 永続ウォレット取引データを設定する

使用します `DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData)` を使用して永続ウォレット取引データを設定します。

* 最大 14 バイトの `byte[]` を Mastercard 2.3 用に渡します。
* 最大 15 バイトの `byte[]` を PURE 用に渡します。

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

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

// 設定するウォレット取引データ（Mastercard に従い 14 バイト）
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 {
    // カード上のウォレット取引データを設定します
    digitalizedCard.setWalletTransactionData(walletTransactionDataToSet);
    
    // ... ここにアプリのロジック。

} catch (InternalComponentException e) {
    // サポートされないスキーム、初期化エラー、またはデータ長の問題などを処理します
}
```

{% endcode %}

{% hint style="info" %}
NFC Wallet SDK は、必要に応じて PURE のウォレット取引データを `00` バイトで埋め、15 バイトに達するようにします。\
NFC Wallet SDK は Mastercard のウォレット取引データを埋めません。
{% endhint %}

#### 永続ウォレット取引データをクリアする

使用します `DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData)` を渡して `null` デジタルカードの保存値をクリアします

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

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

try {
    // 永続ウォレット取引データをクリアします
    digitalizedCard.setWalletTransactionData(null);

} catch (InternalComponentException e) {
    // サポートされないスキーム、初期化エラー、またはデータ長の問題などを処理します
}
```

{% endcode %}

#### 永続ウォレット取引データを取得する

使用します `DigitalizedCard.retrieveWalletTransactionData()` を使用して、デジタルカードに関連付けられたウォレット取引データを取得します。

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

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

try {
    // カードからウォレット取引データを取得します
    byte[] retrievedWalletTransactionData = digitalizedCard.retrieveWalletTransactionData();
    if (retrievedWalletTransactionData != null) {
        // 取得したデータをここで処理します
    } else {
        // ウォレット取引データが見つかりません 
    }

} catch (InternalComponentException e) {
    // サポートされないスキーム、初期化エラー、またはデータ長の問題などを処理します
}
```

{% endcode %}

### 取引中のカード変更を処理する

取引中にカードが変更された場合は、 **デジタルウォレットアプリケーション** は、カードの有効化コールバックが成功した後に、ウォレット取引データモードを再設定する必要があります。

{% 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) {
        // 例外を処理します。
      }
    }
  }
};

// 別のカードで支払いを開始します。
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:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/ja/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.