Mostrar tarjetas digitales

Resumen

Después de Tokenización, su aplicación de cartera digital debería mostrar el usuario final sus tarjetas digitales.

Proporcione una vista de lista y una vista de detalles.

Use el estado de la tarjeta, la ilustración de la tarjeta y los metadatos para guiar la IU.

Integración del SDK

Use DigitalizedCardManager

Después de Tokenización se complete, use DigitalizedCardManager para acceder a la NFC Wallet SDK datos persistentes y recuperar tarjetas digitales.

DigitalizedCardManager admite llamadas asincrónicas y bloqueantes:

• AsyncHandler: Recibe resultados mediante devoluciones de llamada.

• AsyncToken: Bloquea el hilo de llamada hasta que la operación se complete.

AsyncToken bloquea el hilo de llamada. Evítelo en el hilo de la IU.

Recuperar lista de tarjetas

Después de Tokenización se complete, use DigitalizedCardManager.getAllCards() para recuperar todos los IDs de tarjetas tokenizadas.

Para conocer la diferencia entre identificadores, consulte ID de tarjeta tokenizada frente a ID de tarjeta digital.

Los ejemplos a continuación muestran cómo recuperar IDs de tarjetas tokenizadas con AsyncHandler y AsyncToken.

AsyncHandler

Recupere IDs de tarjetas tokenizadas usando AsyncHandler

// Instancie un HandlerThread para evitar trabajo en el hilo de la IU.
val cardDisplayThread = HandlerThread("getAllCards")
cardDisplayThread.start()

val looper = cardDisplayThread.looper

val handler = object : AbstractAsyncHandler<Array<String>>(looper) {
    override fun onComplete(result: AsyncResult<Array<String>>) {
        if (result.isSuccessful) {
            val tokenizedCardIds = result.result
            // TODO: mostrar las tarjetas
        } else {
            // TODO: manejar error
        }
    }
}

DigitalizedCardManager.getAllCards(handler)

AsyncToken

Recupere IDs de tarjetas tokenizadas usando AsyncToken

val token = DigitalizedCardManager.getAllCards(null)
val result = token.waitToComplete()

if (result.isSuccessful) {
    val tokenizedCardIds = result.result
    // Muestre las tarjetas en su IU
} else {
    // Manejar error
}

ID de tarjeta tokenizada frente a ID de tarjeta digital

DigitalizedCardManager lista y recupera tarjetas usando un ID de la tarjeta tokenizada.

DigitalizedCard.getTokenizedCardID() devuelve el ID de tarjeta tokenizada.

Este identificador no es el mismo que el ID de tarjeta digital.

La NFC Wallet SDK usa dos identificadores para la misma tarjeta:

• ID de tarjeta tokenizada: Se genera durante el aprovisionamiento seguro. También se conoce como ID de token CPS. Consulte Activar el aprovisionamiento.

• ID de tarjeta digital: Se genera durante la digitalización. También se conoce como ID de tarjeta MG. Consulte Digitalizar una tarjeta.

Use estos métodos auxiliares para convertir identificadores:

• DigitalizedCardManager.getDigitalCardId(): Obtenga el ID de tarjeta digital a partir de un ID de tarjeta tokenizada.

• DigitalizedCardManager.getTokenizedCardId(): Obtenga el ID de tarjeta tokenizada a partir de un ID de tarjeta digital.

Un TSP también proporciona su propio identificador de tarjeta digital.

Recupérelo en Metadatos de la tarjeta.

Úselo al solucionar problemas con el TSP (VTS/MDES).

Este identificador es diferente del ID de tarjeta tokenizada y del ID de tarjeta digital.

Recuperar información de la tarjeta digital

Use DigitalizedCard

DigitalizedCard representa una tarjeta digitalizada y expone datos de la tarjeta, como:

• DigitalizedCardStatus

  • Estado de la tarjeta: ACTIVE, SUSPENDED

  • Estado de las claves de pago: úselo para detectar necesidades de recarga.

• DigitalizedCardDetails

  • getLastFourDigits() : Últimos cuatro dígitos de FPAN.

  • getLastFourDigitsOfDPAN() : Últimos cuatro dígitos de DPAN.

  • getPANExpiry() : Fecha de vencimiento de FPAN.

  • getScheme(): Red de pago (Visa, Mastercard y PURE).

• DigitalizedCard.getPaymentAccountReference()

  • Referencia de la cuenta de pago (PAR) para la tarjeta sin contacto principal.

Recupere un DigitalizedCard de DigitalizedCardManager usando el ID de la tarjeta tokenizada.

// Obtenga la instancia de DigitalizedCard
val digitalizedCard = DigitalizedCardManager.getDigitalizedCard(tokenizedCardId)

// Obtenga el estado de la tarjeta
val statusToken = digitalizedCard.getCardState(null)
val statusResult = statusToken.waitToComplete()

if (statusResult.isSuccessful) {
    val status = statusResult.result
    
    // Los estados de la tarjeta incluyen ACTIVE y SUSPENDED
    // ACTIVE: La tarjeta puede utilizarse para el pago
    // SUSPENDED: La tarjeta requiere activación antes del pago
    val state = status.state
    
    // Información de las claves de pago
    val numberOfPaymentsLeft = status.numberOfPaymentsLeft
    val needsReplenishment = status.needsReplenishment()
    val expiryDate = status.expiryDate // Fecha de vencimiento de LUK (null para SUK)
}

// Obtenga los detalles de la tarjeta
val detailsToken = digitalizedCard.getCardDetails(null)
val detailsResult = detailsToken.waitToComplete()

if (detailsResult.isSuccessful) {
    val details = detailsResult.result
    
    // Metadatos de la tarjeta
    val lastFourDigits = details.lastFourDigits // Últimos cuatro dígitos de FPAN
    val lastFourDigitsOfDPAN = details.lastFourDigitsOfDPAN // Últimos cuatro dígitos de DPAN
    val panExpiry = details.panExpiry // Fecha de vencimiento de FPAN
    val scheme = details.scheme // Red de pago: Visa, Mastercard, PURE
}

// Obtenga el PAR de la tarjeta principal
try {
    val paymentAccountReference = digitalizedCard.paymentAccountReference
    // Devuelve null si los datos sin contacto no están disponibles o si el PAR no está presente
} catch (e: InternalComponentException) {
    // Manejar error
}

Recuperar información de la tarjeta auxiliar

Si la tarjeta es de doble marca, puede recuperar propiedades adicionales de DigitalizedCard:

• DigitalizedCard.hasAuxiliaryScheme(): Devuelve true si la tarjeta tiene un esquema auxiliar.

• DigitalizedCardDetails

  • getAuxiliaryLastFourDigitsOfDPAN() : Últimos cuatro dígitos del DPAN auxiliar.

  • getAuxiliaryScheme() : Red de pago de la tarjeta auxiliar.

• DigitalizedCard.getAuxiliaryPaymentAccountReference(): Referencia de la cuenta de pago (PAR) para la tarjeta auxiliar sin contacto.

Si la tarjeta no es de doble marca, estas propiedades devuelven null.

// Compruebe si la tarjeta tiene un esquema auxiliar
val hasAuxiliaryScheme = digitalizedCard.hasAuxiliaryScheme()

if (hasAuxiliaryScheme) {
    // Obtenga los detalles de la tarjeta auxiliar
    val detailsToken = digitalizedCard.getCardDetails(null)
    val detailsResult = detailsToken.waitToComplete()
    
    if (detailsResult.isSuccessful) {
        val details = detailsResult.result
        
        // Información del esquema auxiliar
        val auxiliaryScheme = details.auxiliaryScheme // Red de pago auxiliar
        val auxiliaryLastFourDigitsOfDPAN = details.auxiliaryLastFourDigitsOfDPAN // Últimos cuatro dígitos del DPAN auxiliar
    }
    
    // Obtenga la información de las claves de pago auxiliares
    val statusToken = digitalizedCard.getCardState(null)
    val statusResult = statusToken.waitToComplete()
    
    if (statusResult.isSuccessful) {
        val status = statusResult.result
        
        // Pagos restantes para la tarjeta auxiliar
        val auxiliaryNumberOfPaymentsLeft = status.auxiliaryNumberOfPaymentsLeft
    }
    
    // Obtenga el PAR de la tarjeta auxiliar
    try {
        val auxiliaryPaymentAccountReference = digitalizedCard.auxiliaryPaymentAccountReference
        // Devuelve null si:
        // - La tarjeta no tiene un esquema auxiliar
        // - Los datos sin contacto no están disponibles
        // - El PAR no está disponible en los datos sin contacto
    } catch (e: InternalComponentException) {
        // Manejar error
    }
}

// Nota: Si la tarjeta no es de doble marca, las propiedades auxiliares devuelven null

Metadatos de la tarjeta

Use MGCardEnrollmentService.getCardMetaData() y el ID de tarjeta digital para recuperar metadatos de la tarjeta, como:

• nombre del emisor del TSP

• ID del TSP (VTS, MDES u otro identificador)

• PAR (referencia de la cuenta de pago)

• ID de tarjeta digital del TSP (tokenId)

Para obtener cobertura completa de campos, consulte la referencia de la API del SDK.

ID de tarjeta digital del TSP (tokenId) se asigna a:

• Mastercard (MDES): tokenUniqueReference

• Visa (VTS): tokenReferenceID

Ilustración de la tarjeta

Use MobileGatewayManager.getCardArt() y el ID de tarjeta digital para obtener CardArt.

Use CardArt.getBitmap() para recuperar estas imágenes:

• BANK_LOGO: Logotipo del emisor

• CARD_BACKGROUND: Fondo de la tarjeta

• CARD_BACKGROUND_COMBINED: Fondo de la tarjeta combinado con la red de pago

• CARD_ICON: Icono de la tarjeta

La recuperación de la ilustración de la tarjeta genera solicitudes de red; almacene en caché las imágenes dentro de la aplicación de cartera digital para mejorar el rendimiento.

La aplicación de ejemplo demuestra un enfoque simple de almacenamiento en caché local:

Almacenar en caché la ilustración de la tarjeta localmente

fun getCardArt(context: Context, digitalCardId: String) {
    // Primero compruebe si ya tenemos la imagen localmente
    val imageBytes = readFromFile(context, digitalCardId)
    if (imageBytes.isNotEmpty()) {
        val image = BitmapDrawable(
            context.resources,
            BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.size)
        )
        // Use la imagen almacenada en caché en su IU
        return
    }

    // Descargue los datos de la ilustración de la tarjeta desde el backend
    val gatewayManager = MobileGatewayManager.INSTANCE
    try {
        val cardArt = gatewayManager.getCardArt(digitalCardId)
        cardArt.getBitmap(
            CardArtType.CARD_BACKGROUND_COMBINED,
            object : MGAbstractAsyncHandler<CardBitmap>() {
                override fun onComplete(result: MGAsyncResult<CardBitmap>) {
                    if (result.isSuccessful) {
                        val value = result.result
                        // Almacene los datos para uso futuro
                        writeToFile(context, digitalCardId, value.resource)
                        val image = BitmapDrawable(
                            context.resources,
                            BitmapFactory.decodeByteArray(
                                value.resource,
                                0,
                                value.resource.size
                            )
                        )
                        // Use la imagen descargada en su IU
                    }
                }
            }
        )
    } catch (exception: NoSuchCardException) {
        // Manejar error: tarjeta no encontrada
    }
}