Añadir datos de transacción de la cartera

Adjuntar datos de transacción de la cartera a pagos sin contacto de Mastercard y PURE.

Resumen

Puede adjuntar datos de transacción de la cartera a un pago sin contacto. El host de procesamiento puede usar estos datos durante el procesamiento de autorización.

Los datos de transacción de la cartera se definen para cada tarjeta digital. Puede proporcionarlos de dos maneras:

• Persistente: El SDK almacena los datos en almacenamiento seguro. Sigue disponible después de que la aplicación de cartera digital se reinicie.
• Efímero: La aplicación de cartera digital proporciona los datos solo para una transacción.

La aplicación de cartera digital decide si incluir estos datos en cada pago.

Esta función es compatible con los perfiles de pago sin contacto Mastercard (MCBP 2.3) y PURE.

Antes de una transacción, se debe establecer el modo de datos de transacción de la cartera para especificar si se usarán los datos persistentes almacenados o los datos personalizados efímeros.

El modo de datos de transacción de la cartera se restablece después de cada transacción y debe volver a establecerse si la tarjeta cambia durante una transacción.

Las siguientes API están obsoletas a partir de 6.14.0:

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

Use las API introducidas en 6.14.0 para nuevas integraciones.

Perfiles compatibles

Mastercard (MCBP 2.3)

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

Si los datos de transacción de la cartera están disponibles antes de una transacción sin contacto, el SDK actualiza el IAD (etiqueta EMV 9F10, Datos de 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 la cartera: 14 bytes

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

PURE sin contacto

Si los datos de transacción de la cartera están disponibles antes de una transacción sin contacto, el SDK actualiza el IAD (etiqueta EMV 9F10, Datos de 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 la cartera: 15 bytes

Integración del SDK

Establecer el modo de datos de transacción de la cartera

Establezca el modo de datos de transacción de la cartera antes de que comience la transacción.

Use PaymentBusinessService.setWalletTransactionDataMode(WalletTransactionDataMode) para seleccionar cómo el SDK proporciona los datos de transacción de la cartera para el siguiente pago.

Modos disponibles:

• Modo de almacenamiento: Use los datos de transacción de la cartera predeterminados almacenados para la tarjeta digital.
• Modo efímero: Establezca datos de transacción de la cartera solo para la siguiente transacción. Estos datos no se almacenarán.

El modo de datos de transacción de la cartera se restablece:

• cuando cambia la tarjeta durante una transacción. Consulte Gestionar un cambio de tarjeta durante una transacción.
• después de la transacción, independientemente del estado (éxito, fallo o cancelación)

Usar el modo de almacenamiento

En el siguiente fragmento de código, la aplicación de cartera digital notifica al NFC Wallet SDK que use los datos persistentes de transacción de la cartera para la siguiente transacción.

// Establecer los datos de transacción de la cartera predeterminados para una transacción de pago.
PaymentBusinessManager.getPaymentBusinessService().
setWalletTransactionDataMode(WalletTransactionDataMode.storage());

Consulte Administrar datos persistentes de transacción de la cartera para obtener detalles sobre cómo establecer datos persistentes de transacción de la cartera para cada tarjeta digital.

Usar el modo efímero

En el siguiente fragmento de código, la aplicación de cartera digital proporciona al NFC Wallet SDK los datos efímeros de transacción de la cartera para la siguiente transacción.

Para Mastercard, la carga útil puede contener hasta 14 bytes. Para PURE, puede contener hasta 15 bytes.

// Establecer datos personalizados de transacción de la cartera para una transacción de pago.
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 rellena los datos de transacción de la cartera PURE con 00 bytes cuando es necesario para alcanzar 15 bytes. NFC Wallet SDK no rellena los datos de transacción de la cartera Mastercard.

Administrar datos persistentes de transacción de la cartera

Los datos de transacción de la cartera almacenados están asociados a una tarjeta digital. El SDK usa este valor si selecciona el modo de almacenamiento.

Establecer datos persistentes de transacción de la cartera

Use DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData) para establecer datos persistentes de transacción de la cartera.

• Pase hasta 14 bytes byte[] para Mastercard 2.3.
• Pase hasta 15 bytes byte[] para PURE.

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

// Datos de transacción de la cartera que se van a establecer (14 bytes según 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 {
    // Establecer los datos de transacción de la cartera en la tarjeta
    digitalizedCard.setWalletTransactionData(walletTransactionDataToSet);
    
    // ... Lógica de la aplicación aquí .

} catch (InternalComponentException e) {
    // Gestionar problemas como esquema no compatible, error de inicialización o problema de longitud de datos
}

NFC Wallet SDK rellena los datos de transacción de la cartera PURE con 00 bytes cuando es necesario para alcanzar 15 bytes. NFC Wallet SDK no rellena los datos de transacción de la cartera Mastercard.

Borrar datos persistentes de transacción de la cartera

Use DigitalizedCard.setWalletTransactionData(byte[] walletTransactionData) y pase null para borrar el valor almacenado para la tarjeta digital

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

try {
    // Borrar los datos persistentes de transacción de la cartera
    digitalizedCard.setWalletTransactionData(null);

} catch (InternalComponentException e) {
    // Gestionar problemas como esquema no compatible, error de inicialización o problema de longitud de datos
}

Recuperar datos persistentes de transacción de la cartera

Use DigitalizedCard.retrieveWalletTransactionData() para recuperar los datos de transacción de la cartera asociados a la tarjeta digital.

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

try {
    // Recuperar los datos de transacción de la cartera de la tarjeta
    byte[] retrievedWalletTransactionData = digitalizedCard.retrieveWalletTransactionData();
    if (retrievedWalletTransactionData != null) {
        // Procesar los datos recuperados aquí
    } else {
        // No se encontraron datos de transacción de la cartera 
    }

} catch (InternalComponentException e) {
    // Gestionar problemas como esquema no compatible, error de inicialización o problema de longitud de datos
}

Gestionar un cambio de tarjeta durante una transacción

Si la tarjeta cambia durante la transacción, la aplicación de cartera digital debe establecer el modo de datos de transacción de la cartera nuevamente después de una devolución de llamada exitosa de activación de la tarjeta.

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) {
        // Gestionar excepciones.
      }
    }
  }
};

// Iniciar un pago con una tarjeta diferente.
paymentBusinessService.activateNonDefaultCard(
    cardBTokenId,
    PaymentType.CONTACTLESS,
    keepAsDefault,
    paymentServiceListener,
    activationListener
);