Add wallet transaction data

Attach wallet transaction data to Mastercard and PURE contactless payments.

Overview

You can attach wallet transaction data to a contactless payment. The processing host can use this data during authorization processing.

Wallet transaction data is defined for each digital card. You can provide it in two ways:

• Persistent: The SDK stores the data in secure storage. It remains available after the digital wallet application restarts.
• Ephemeral: The digital wallet application provides the data for one transaction only.

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

This feature is supported for Mastercard (MCBP 2.3) and PURE contactless payment profiles.

Before a transaction, the wallet transaction data mode must be set to specify whether to use stored persistent data or ephemeral custom data.

The wallet transaction data mode resets after each transaction and must be re-established if the card changes during a transaction.

The following APIs are deprecated as of 6.14.0:

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

Use the APIs introduced in 6.14.0 for new integrations.

Supported profiles

Mastercard (MCBP 2.3)

NFC Wallet SDK supports Mastercard specification MCBP 2.3.

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

In MCBP 2.3, this feature is called wallet proprietary information.

PURE contactless

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

Set the wallet transaction data mode before the transaction starts.

Use PaymentBusinessService.setWalletTransactionDataMode(WalletTransactionDataMode) to select how the SDK supplies wallet transaction data for the next payment.

Available modes:

• Storage mode: Use the default wallet transaction data stored for the digital card.
• Ephemeral mode: Set a wallet transaction data for the next transaction only. This data will not be stored.

Wallet transaction data mode is reset:

• on card change during a transaction. See Handle a card change during a transaction.
• after the transaction, regardless of status (success, failure, or cancellation)

Use storage mode

In the code snipet below the digital wallet application notifies the NFC Wallet SDK to use the persistent wallet transaction data for the next transaction.

// Set default wallet transaction data for a payment transaction.
PaymentBusinessManager.getPaymentBusinessService().
setWalletTransactionDataMode(WalletTransactionDataMode.storage());

See Manage persistent wallet transaction data for details on setting persistent wallet transaction data for each digital card.

Use ephemeral mode

In the code snipet below the digital wallet application is providing to the NFC Wallet SDK the ephemeral wallet transaction data for the next transaction.

For Mastercard, the payload can contain up to 14 bytes. For PURE, it can contain up to 15 bytes.

// Set custom wallet transaction data for a payment transaction.
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 pads PURE wallet transaction data with 00 bytes when needed to reach 15 bytes. NFC Wallet SDK does not pad Mastercard wallet transaction data.

Manage persistent wallet transaction data

Stored wallet transaction data is associated with a digital card. The SDK uses this value if you select the storage mode.

Set persistent wallet transaction data

Use DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData) to set persistent wallet transaction data.

• Pass up to 14-byte byte[] for Mastercard 2.3.
• Pass up to 15-byte byte[] for PURE.

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

// Wallet transaction data to set (14 bytes as per Mastercard)
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 {
    // Set the wallet transaction data on the card
    digitalizedCard.setWalletTransactionData(walletTransactionDataToSet);
    
    // ... App logic here .

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}

NFC Wallet SDK pads PURE wallet transaction data with 00 bytes when needed to reach 15 bytes. NFC Wallet SDK does not pad Mastercard wallet transaction data.

Clear persistent wallet transaction data

Use DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData) and pass null to clear the stored value for the digital card

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

try {
    // Clear the persistent wallet transaction data
    digitalizedCard.setWalletTransactionData(null);

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}

Retrieve persistent wallet transaction data

Use DigitalizedCard.retrieveWalletTransactionData() to retrieve the wallet transaction data associated with the digital card.

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

try {
    // Retrieve the wallet transaction data from the card
    byte[] retrievedWalletTransactionData = digitalizedCard.retrieveWalletTransactionData();
    if (retrievedWalletTransactionData != null) {
        // Process the retrieved data here
    } else {
        // No wallet transaction data found 
    }

} catch (InternalComponentException e) {
    // Handle issues such as unsupported scheme, initialization error, or data length problem
}

Handle a card change during a transaction

If the card changes during the transaction, the digital wallet application must set the wallet transaction data mode again after a successful card activation callback.

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) {
        // Handle exceptions.
      }
    }
  }
};

// Start a payment with a different card.
paymentBusinessService.activateNonDefaultCard(
    cardBTokenId,
    PaymentType.CONTACTLESS,
    keepAsDefault,
    paymentServiceListener,
    activationListener
);