Ver y controlar tarjetas digitales

Se requiere el servicio de tokenización para usar Thales D1 SDK para las capacidades "View&Control".

Usa esta guía para permitir que el Usuario final vea y gestione tarjetas digitales (tokens) creados para sus tarjetas en xPay Wallets y otros solicitantes de tokens.

En la aplicación del emisor, normalmente:

• mostrar todas las tarjetas digitales vinculadas a un cardId
• mostrar el estado de cada tarjeta digital (por ejemplo, activa o suspendida)
• admitir acciones básicas del ciclo de vida como suspender, reanudar, eliminar y activar

Requisitos previos

Asegúrate de que:

• El Usuario final y la tarjeta están registrados en el backend de D1.
• El D1 SDK está integrado en tu aplicación del emisor e inicializado.
• La aplicación del emisor ha completado el flujo de inicio de sesión de D1 SDK.

Para el flujo de tokenización de billetera de extremo a extremo, consulta Implementar push a billeteras digitales.

Ver tarjetas digitales

Para mostrar las tarjetas digitales existentes para un cardId, llama a getDigitalCardList().

La respuesta contiene una lista de DigitalCard objetos. Para Visa Cloud Token Framework (CTF), el DigitalCard objeto también incluye información de vinculación de dispositivo, lo que permite a la aplicación ver todas las vinculaciones de dispositivo asociadas con cada tarjeta digital.

El DigitalCard contiene la siguiente información:

• Estado de la tarjeta digital (por ejemplo, activa, suspendida o pendiente de activación).
• Fecha de expiración de la tarjeta digital.
• Últimos cuatro dígitos de la tarjeta digital.
• Nombre y tipo del dispositivo que contiene la tarjeta digital.
• ID del solicitante de token (tokenRequestorID).
• Si la tarjeta digital está en el dispositivo actual (isOnCurrentDevice) para la billetera o solicitante de token seleccionado (por ejemplo, Apple Pay, Google Pay, Samsung Pay o NFC Wallet).
• Lista de vinculaciones de dispositivo (desde SDK 4.3.0 para Visa CTF). Contiene la referencia de vinculación, el nombre del dispositivo y el estado de vinculación (APPROVED, DECLINED o CHALLENGED) para cada dispositivo vinculado.

Debido a limitaciones de la red de pagos, no siempre puedes recuperar el nombre y el logotipo del solicitante de token en tiempo real.

Como buena práctica, identifica los 5 a 10 ID de solicitante de token más relevantes para tu cartera y codifica de forma fija un nombre para mostrar y un logotipo visibles para el Usuario final en la aplicación del emisor.

Flujo

Flujo de alto nivel para listar tarjetas digitales de una tarjeta.

Diagrama de secuencia

Requisitos previos

• La cuenta del consumidor y la tarjeta se registraron en D1
• El SDK está inicializado correctamente
• La aplicación del emisor llamó a la API de inicio de sesión de D1 SDK

Ejemplo de interfaz de la aplicación del emisor para listar tarjetas digitales.

Ejemplos

Android

fun getDigitalCardList(d1Task: D1Task, cardID: String) {
    val callback: D1Task.Callback<List<DigitalCard>> = object : D1Task.Callback<List<DigitalCard>> {

        override fun onSuccess(digitalCardList: List<DigitalCard>) {
            // Maneja el objeto digitalCardList del servidor.
            // Por ejemplo, para mostrarlo en la interfaz de usuario como en la imagen de ejemplo anterior.
            for (digitalCard in digitalCardList) {
                val digitalCardID = digitalCard.cardID
                val digitalCardState = digitalCard.state // Estado de la tarjeta digital actual.
                val digitalCardExp = digitalCard.expiryDate // Fecha de expiración de la tarjeta digital actual.
                val last4 = digitalCard.last4 // Últimos 4 dígitos de la tarjeta digital actual.
                val tokenRequestorID = digitalCard.tokenRequestorID // ID del solicitante de token.
                val isOnCurrentDevice = digitalCard.isOnCurrentDevice //Identifica si la tarjeta digital está en el dispositivo actual.

                // Recupera la lista de vinculaciones de dispositivo (desde SDK 4.3.0 para Visa CTF).
                val deviceBindingList = digitalCard.deviceBindingList
                deviceBindingList?.forEach { binding ->
                    val bindingReference = binding.bindingReference // ID de referencia de vinculación.
                    val deviceName = binding.deviceName // Nombre del dispositivo.
                    val bindingStatus = binding.bindingStatus // APPROVED, DECLINED, or CHALLENGED.
                }
            }
        }

        override fun onError(exception: D1Exception) {
            // Consulta la sección Integración de D1 SDK – Gestión de errores.
        }
    }
    d1Task.getDigitalCardList(cardID, callback)
}

iOS >= 4.5.0

let cardID = "" // obtenido, por ejemplo, del servidor
do {
    let service = try d1Task.digitalCardService()
    let digitalCards = try await service.digitalCardList(cardID)
    // Continúa con los flujos posteriores, por ejemplo, actualizar la interfaz de usuario
    for digitalCard in digitalCards {
        print("ID de tarjeta digital: \(digitalCard.cardID)")
        print("Estado: \(digitalCard.state.rawValue)")
        print("Últimos 4: \(digitalCard.last4 ?? "")")
        print("Expiración: \(digitalCard.expiryDate ?? "")")
        print("ID del dispositivo: \(digitalCard.deviceID ?? "")")
        print("Nombre del dispositivo: \(digitalCard.deviceName ?? "")")
        print("Tipo de dispositivo: \(digitalCard.deviceType ?? "")")
        print("ID del solicitante de token: \(digitalCard.tokenRequestorID ?? "")")
        print("Nombre del solicitante de token: \(digitalCard.tokenRequestorName ?? "")")
        print("Está en el dispositivo actual: \(digitalCard.isOnCurrentDevice)")
        
        // Accede a la lista de vinculaciones de dispositivo (desde SDK 4.3.0)
        if let deviceBindingList = digitalCard.deviceBindingList {
            for binding in deviceBindingList {
                print("Referencia de vinculación: \(binding.bindingReference ?? "")")
                print("Nombre del dispositivo: \(binding.deviceName ?? "")")
                print("Estado de vinculación: \(binding.bindingStatus?.rawValue ?? "")")
            }
        }
    }
} catch let d1Error as D1Error {
    // Consulta la sección Integración de D1 SDK – Gestión de errores
} catch let error {
    // Maneja otros errores
}

iOS < 4.5.0

let cardID = "" // Obtenido, por ejemplo, del servidor.
d1Task.digitalCardList(cardID) { digitalCards, error in
    if let error = error {
        // Consulta la sección Integración de D1 SDK – Gestión de errores.
    } else if let digitalCards = digitalCards {
        // Continúa con los flujos posteriores. Por ejemplo, actualiza la interfaz de usuario.
        for digitalCard in digitalCards {
            print("ID de tarjeta digital: \(digitalCard.cardID)")
            print("Estado: \(digitalCard.state.rawValue)")
            print("Últimos 4: \(digitalCard.last4 ?? "")")
            print("Expiración: \(digitalCard.expiryDate ?? "")")
            print("ID del dispositivo: \(digitalCard.deviceID ?? "")")
            print("Nombre del dispositivo: \(digitalCard.deviceName ?? "")")
            print("Tipo de dispositivo: \(digitalCard.deviceType ?? "")")
            print("ID del solicitante de token: \(digitalCard.tokenRequestorID ?? "")")
            print("Está en el dispositivo actual: \(digitalCard.isOnCurrentDevice)")

            // Recupera la lista de vinculaciones de dispositivo (desde SDK 4.3.0 para Visa CTF).
            if let deviceBindingList = digitalCard.deviceBindingList {
                for binding in deviceBindingList {
                    print("Referencia de vinculación: \(binding.bindingReference ?? "")")
                    print("Nombre del dispositivo: \(binding.deviceName ?? "")")
                    print("Estado de vinculación: \(binding.bindingStatus?.rawValue ?? "")")
                }
            }
        }
    }
}

Controlar tarjetas digitales

La aplicación del emisor puede permitir que el Usuario final gestione el estado de cada tarjeta digital.

Las acciones admitidas incluyen:

• Suspender una tarjeta digital cuando el estado actual es activo: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.SUSPEND, callback)
• Reanudar una tarjeta digital cuando el estado actual es suspendido: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.RESUME, callback)
• Eliminar una tarjeta digital: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.DELETE, callback)
• Activar una tarjeta digital (por ejemplo, después de la autenticación reforzada): d1PushWallet.activateDigitalCard(digitalCard.getCardID(), callback)

Diagrama de secuencia

Requisitos previos

• La cuenta del consumidor y la tarjeta se registraron en D1
• El SDK está inicializado correctamente
• La aplicación del emisor llamó a la API de inicio de sesión de D1 SDK

Ejemplo de interfaz de la aplicación del emisor para controlar el estado de una tarjeta digital.

Ejemplos

Android

//digitalCard: recuperada de la API getDigitalCardList
fun controlDigitalCard(d1Task: D1Task, cardID: String, digitalCard: DigitalCard) {
    val callback: D1Task.Callback<Boolean> = object : D1Task.Callback<Boolean> {

        override fun onSuccess(isSuccess: Boolean) {
            if (isSuccess) {
                // El estado de la tarjeta digital se ha actualizado correctamente.
                // La aplicación puede actualizar la interfaz de usuario.
            } else {
                // La actualización del estado de la tarjeta digital ha fallado.
            }
        }

        override fun onError(exception: D1Exception) {
            // Consulta la sección Integración de D1 SDK – Gestión de errores.
        }
    }

    // Si el estado actual de la tarjeta digital es ACTIVE
    d1Task.updateDigitalCard(cardID, digitalCard, CardAction.SUSPEND, callback)
}

iOS >= 4.5.0

let cardID = "" // obtenido, por ejemplo, del servidor
// Si el estado actual de la tarjeta digital es ACTIVE
// digitalCard se recupera de la API D1Task.digitalCardList
do {
    let service = try d1Task.digitalCardService()
    try await service.updateDigitalCard(cardID, digitalCard: digitalCard, action: .suspend)
} catch let d1Error as D1Error {
    // Consulta la sección Integración de D1 SDK – Gestión de errores
} catch let error {
    // Maneja otros errores
}

iOS < 4.5.0

let cardID = "" // obtenido, por ejemplo, del servidor
// Si el estado actual de la tarjeta digital es ACTIVE
// digitalCard se recupera de la API D1Task.digitalCardList
d1Task.updateDigitalCard(cardID, digitalCard: digitalCard, action: .suspend) { isSuccess, error in
    if let error = error {
        // Consulta la sección Integración de D1 SDK – Gestión de errores
    } else {
        if isSuccess {
            // Continúa con los flujos posteriores, por ejemplo, actualizar la interfaz de usuario
        } else {
            // El fallo podría deberse a un estado no válido; por ejemplo, actualizar una tarjeta activa al estado activo
        }
    }
}

Para tener acceso completo a D1 SDK, consulta Referencia de la API.