Add wallet transaction data

Overview

You can attach wallet transaction data to a contactless payment.

The issuer backend can use this data during authorization processing.

Wallet transaction data is defined per digital card.

The digital wallet application can provide it in two modes:

• Persistent: The NFC Wallet SDK stores the data in secure storage. It persists across application restarts.
• Ephemeral: The digital wallet application provides the value for one transaction only.

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

The NFC Wallet SDK supports wallet transaction data for Mastercard and PURE contactless profiles only.

Mastercard specification (MCBP 2.3)

The NFC Wallet SDK supports Mastercard specification MCBP 2.3.

If wallet transaction data is available before a contactless transaction, the NFC Wallet 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 named wallet proprietary information.

PURE specification

The NFC Wallet SDK also supports wallet transaction data for PURE contactless profiles.

If wallet transaction data is available before a contactless transaction, the NFC Wallet 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 persistent wallet transaction data for Mastercard

Use DigitalCard.setWalletTransactionData to set persistent wallet transaction data:

• Pass a 14-byte Data value to store wallet transaction data for this digital card.
• Pass nil to clear the stored value for this digital card.

do {      
    // Set wallet transaction data for Mastercard, data length = 14 bytes.
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Clear wallet transaction data for this card
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Handle the error  
}

Set persistent wallet transaction data for PURE

Use DigitalCard.setWalletTransactionData to set persistent wallet transaction data:

• Pass a 15-byte Data value to store wallet transaction data for this digital card.
• Pass nil to clear the stored value for this digital card.

do {      
    // Set wallet transaction data for this specific card
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Clear wallet transaction data for this card
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Handle the error  
}

Handle errors

The wallet transaction data must meet the following requirements:

• Length for Mastercard: Exactly 14 bytes
• Length for PURE: Exactly 15 bytes
• Scheme support: Only Mastercard and PURE contactless profiles are supported. If you set wallet transaction data for another scheme, the SDK returns .schemeNotSupported.

do {
      try await digitalCard.setWalletTransactionData(data)
  } catch DigitalCard.Error.invalidWalletTransactionData {
      // Scheme based length validation.
      // For Mastercard, the data length is not 14 bytes. 
      // For PURE card, the data length is not 15 bytes. 
  } catch DigitalCard.Error.schemeNotSupported {
      // Card scheme does not support wallet transaction data (e.g., Visa)
  } catch {
      // Other errors
  }

Provide wallet transaction data for a payment

Use startPayment() with ContactlessPaymentInputData to provide wallet transaction data during a contactless payment.

ContactlessPaymentInputData supports two wallet transaction data modes:

• .storage: Use the value stored in secure storage (if set).
• .ephemeral: Provide a value for this transaction only.

Storage mode

let paymentInputData = ContactlessPaymentInputData(
    digitalCardID: card.id,
    walletTransactionDataMode: .storage
)

Ephemeral mode

let paymentInputData = ContactlessPaymentInputData(
    digitalCardID: card.id,
    walletTransactionDataMode: .ephemeral(customData)
)

Start a payment

// start payment with provided contactlessPaymentInputData
// use case: manual mode (with user interaction)
await session.startPayment(with contactlessPaymentInputData: contactlessPaymentInputData)