> 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`、イシュア Application Data):

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

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

#### PURE 非接触

非接触取引の前にウォレット取引データが利用可能な場合、SDK は次を更新します `IAD` (EMV タグ `9F10`、イシュア 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, and the optional `goal` query parameter:

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