ウォレット取引データを追加する

MastercardおよびPUREの非接触決済にウォレット取引データを添付します。

概要

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

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

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

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

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

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

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

以下の API は、以降非推奨です 6.14.0:

• DigitalizedCard.setWalletTransactionData(WalletTransactionData walletTransactionData)
• DigitalizedCard.getWalletTransactionData()
• PaymentBusinessService.setWalletTransactionData(WalletTransactionData walletTransactionData)

で導入された API を使用してください 6.14.0 新しい統合では。

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

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 が次の支払いにウォレット取引データをどのように提供するかを選択します。

利用可能なモード:

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

ウォレット取引データモードは次の場合にリセットされます:

• 取引中にカードが変更されたとき。参照: 取引中のカード変更を処理する.
• 取引後、状態（成功、失敗、キャンセル）に関係なく

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

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

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

参照 永続的なウォレット取引データを管理する 各デジタルカードの永続的なウォレット取引データの設定の詳細。

一時モードを使用する

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

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

// 支払い取引のカスタムウォレット取引データを設定します。
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));

NFC Wallet SDK は PURE のウォレット取引データを次でパディングします 00 必要に応じて 15 バイトに達するまでバイトを追加します。 NFC Wallet SDK は Mastercard のウォレット取引データをパディングしません。

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

保存されたウォレット取引データはデジタルカードに関連付けられています。SDK は、次を選択した場合にこの値を使用します ストレージモード.

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

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

• 14 バイトまでの byte[] Mastercard 2.3 用。
• 15 バイトまでの byte[] PURE 用。

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) {
    // サポートされていないスキーム、初期化エラー、またはデータ長の問題などを処理します
}

NFC Wallet SDK は PURE のウォレット取引データを次でパディングします 00 必要に応じて 15 バイトに達するまでバイトを追加します。 NFC Wallet SDK は Mastercard のウォレット取引データをパディングしません。

永続的なウォレット取引データを消去する

使用する DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData) および null デジタルカードに保存された値を消去するには

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

try {
    // 永続的なウォレット取引データを消去します
    digitalizedCard.setWalletTransactionData(null);

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

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

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

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

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

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

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

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

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
);