Agregar datos de transacciones de la cartera

Descripción general

Puede adjuntar datos de transacciones de wallet a un pago sin contacto.

El backend del emisor puede usar estos datos durante el procesamiento de la autorización.

Los datos de transacción de wallet se definen por tarjeta digital.

La aplicación de cartera digital puede proporcionarlos en dos modos:

• Persistente: El SDK de NFC Wallet almacena los datos en almacenamiento seguro. Persiste entre reinicios de la aplicación.

• Efímero: La aplicación de cartera digital proporciona el valor solo para una transacción.

La aplicación de cartera digital decide si incluir los datos de transacción de wallet en cada pago.

El SDK de NFC Wallet admite datos de transacción de wallet solo para los perfiles sin contacto Mastercard y PURE.

Especificación Mastercard (MCBP 2.3)

El SDK de NFC Wallet admite la especificación Mastercard MCBP 2.3.

Si los datos de transacción de wallet están disponibles antes de una transacción sin contacto, el SDK de NFC Wallet actualiza el IAD (tag EMV 9F10, Datos de la aplicación del emisor):

• Desplazamiento inicial: byte 19

• Longitud máxima del IAD: 32 bytes

• Longitud máxima de los datos de transacción de wallet: 14 bytes

En MCBP 2.3, esta función se denomina información propietaria de wallet.

Especificación PURE

El SDK de NFC Wallet también admite datos de transacción de wallet para perfiles sin contacto PURE.

Si los datos de transacción de wallet están disponibles antes de una transacción sin contacto, el SDK de NFC Wallet actualiza el IAD (tag EMV 9F10, Datos de la aplicación del emisor):

• Desplazamiento inicial: byte 18

• Longitud máxima del IAD: 32 bytes

• Longitud máxima de los datos de transacción de wallet: 15 bytes

Integración del SDK

Establecer datos persistentes de transacción de wallet para Mastercard

Use DigitalCard.setWalletTransactionData para establecer datos persistentes de transacción de wallet:

• Pasar un valor de Data de 14 bytes para almacenar los datos de transacción de wallet de esta tarjeta digital.

• Pasar nil para borrar el valor almacenado de esta tarjeta digital.

do {      
    // Establecer datos de transacción de wallet para Mastercard; longitud de los datos = 14 bytes.
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Borrar los datos de transacción de wallet de esta tarjeta
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Manejar el error  
}

Establecer datos persistentes de transacción de wallet para PURE

Use DigitalCard.setWalletTransactionData para establecer datos persistentes de transacción de wallet:

• Pasar un valor de 15 bytes Data de 14 bytes para almacenar los datos de transacción de wallet de esta tarjeta digital.

• Pasar nil para borrar el valor almacenado de esta tarjeta digital.

do {      
    // Establecer datos de transacción de wallet para esta tarjeta específica
    let walletData = Data([0x57, 0x61, 0x6C, 0x6C, 0x65, 0x74, 0x44,
                            0x61, 0x74, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00])      
    try await digitalCard.setWalletTransactionData(walletData)
    // Borrar los datos de transacción de wallet de esta tarjeta
    try await digitalCard.setWalletTransactionData(nil)  
} catch {
    // Manejar el error  
}

Manejar errores

Los datos de transacción de wallet deben cumplir los siguientes requisitos:

• Longitud para Mastercard: exactamente 14 bytes

• Longitud para PURE: exactamente 15 bytes

• Compatibilidad con el esquema: solo se admiten los perfiles sin contacto Mastercard y PURE. Si establece datos de transacción de wallet para otro esquema, el SDK devuelve .schemeNotSupported.

do {
      try await digitalCard.setWalletTransactionData(data)
  } catch DigitalCard.Error.invalidWalletTransactionData {
      // Validación de longitud según el esquema.
      // Para Mastercard, la longitud de los datos no es de 14 bytes. 
      // Para la tarjeta PURE, la longitud de los datos no es de 15 bytes. 
  } catch DigitalCard.Error.schemeNotSupported {
      // El esquema de la tarjeta no admite datos de transacción de wallet (por ejemplo, Visa)
  } catch {
      // Otros errores
  }

Proporcionar datos de transacción de wallet para un pago

Use startPayment() con ContactlessPaymentInputData para proporcionar datos de transacción de wallet durante un pago sin contacto.

ContactlessPaymentInputData admite dos modos de datos de transacción de wallet:

• .storage: Usa el valor almacenado en el almacenamiento seguro (si está configurado).

• .ephemeral: Proporciona un valor solo para esta transacción.

Modo de almacenamiento

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

Modo efímero

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

Iniciar un pago

// iniciar el pago con el contactlessPaymentInputData proporcionado
// caso de uso: modo manual (con interacción del usuario)
await session.startPayment(with contactlessPaymentInputData: contactlessPaymentInputData)