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

ウォレットのトランザクションデータを 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、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 が次の決済に対してウォレット取引データをどのように提供するかを選択するために使用します。

利用可能なモード:

• ストレージモード: デジタルカード用に保存されたデフォルトのウォレット取引データを使用します。

• 一時モード: 次の取引に対してのみウォレット取引データを設定します。このデータは保存されません。

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

• 取引中のカード変更時。参照してください 取引中のカード変更を処理する.

• 取引後、ステータスに関係なく（成功、失敗、またはキャンセル）

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

以下のコードスニペットでは、デジタルウォレットアプリケーションが 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
);