Obtener el estado de digitalización de la tarjeta

Obtener el estado de digitalización de la tarjeta

Utilice esta guía para determinar si una tarjeta ya está digitalizada en una billetera específica del dispositivo. La aplicación emisora usa este estado para decidir si mostrar Añadir a la billetera o Activar tarjeta, o para ocultar ambas.

Normalmente llama a esta API cuando:

• la aplicación emisora se inicia, o
• el usuario final abre una pantalla de detalles de la tarjeta.

Para ver el flujo general de push provisioning, consulte Implementar push en billeteras digitales.

Descripción general

La aplicación emisora usa el SDK D1 para comprobar el estado de tokenización de la tarjeta en el dispositivo móvil. Según el estado devuelto, la aplicación emisora actualiza la interfaz de usuario:

• DIGITALIZADA – La tarjeta ya está tokenizada en la billetera de este dispositivo. Ocultar Añadir a la billetera y Activar tarjeta.
• NO_DIGITIZADA – La tarjeta no está tokenizada. Mostrar Añadir a la billetera.
• PENDIENTE_IDV – La tarjeta digital se ha creado pero está pendiente de ID&V. Mostrar Activar tarjeta si se admite la autenticación dentro de la app.

Precaución

• Si la tarjeta todavía aparece como NO_DIGITIZADA después de la digitalización, compruebe que la aplicación emisora esté correctamente configurada en el portal TSP.
• Para Samsung Pay, algunos emisores deben registrar varios nombres de emisor en el portal. Asegúrese de que el nombre de emisor usado en la API coincida con los nombres registrados en el portal. Solo se devuelven coincidencias exactas. Consulte las preguntas frecuentes de Samsung para obtener consejos de solución de problemas.

Flujo

Flujo de alto nivel para recuperar el estado de digitalización de la tarjeta antes del push provisioning.

Diagrama de secuencia

Requisitos previos

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

Secuencia de alto nivel para recuperar el estado de digitalización de la tarjeta desde la billetera.

Integración de plataforma

Android

En Android, el SDK D1 devuelve un CardDigitizationState a través de la getCardDigitizationState() API para la billetera seleccionada, como Google Pay o Samsung Pay.

Los estados posibles son:

• DIGITALIZADA La tarjeta ya ha sido tokenizada. No se requiere ningún mensaje ni acción.
• NO_DIGITIZADA Muestre un Añadir a Google/Samsung Pay botón. Consulte las directrices de marca de Google Pay para obtener más información. El siguiente paso es enviar la tarjeta a la billetera, como se explica en Enviar a la billetera digital.
• PENDIENTE_IDV Muestre un Activar tarjeta botón si se admite la autenticación de la aplicación emisora. Tras una autenticación correcta, llame a activateDigitalCard() para activar la tarjeta digital.

Use la API que coincida con el identificador de tarjeta disponible en la aplicación emisora:

• Use D1PushWallet.getCardDigitizationState(cardID, wallet) cuando disponga del cardID.
• Para D1 SDK v4.4.0 y versiones posteriores, use PushProvisioningService.getCardDigitizationState(wallet, last4) cuando solo tenga los últimos cuatro dígitos, por ejemplo, de los metadatos de la tarjeta.

Use card ID

Use esta API cuando la aplicación emisora tenga el cardID.

// Para Android versión 4.4.0 y superior
fun checkCardDigitizationState_v4_4_0(d1Task: D1Task, cardID: String) {
    val pushProvisioningService = d1Task.pushProvisioningService
    val wallet = OEMPayType.GOOGLE_PAY // puede ser SAMSUNG_PAY
    activity.lifecycleScope.launch {
        try {
            val state = withContext(Dispatchers.IO) {
                pushProvisioningService.getCardDigitizationState(cardID, wallet).await()
            }
            // Actualice la interfaz de usuario según el valor del estado

            // Ocultar botón "Añadir a Google/Samsung Pay"
            // Ocultar botón "Activar tu tarjeta"
            when (state) {
                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.NOT_DIGITIZED -> {
                    // Mostrar botón "Añadir a Google/Samsung Pay"
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.PENDING_IDV -> {
                    // 1. Mostrar botón "Activar tu tarjeta"
                    // 2. Autenticar al usuario final
                    // 3. Realizar activación: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.DIGITIZED -> {
                    // Ocultar botón "Añadir a Google/Samsung Pay"
                }

                else -> {
                    //No hacer nada
                }
            }
        } catch (exception: D1Exception) {
            // Consulte la sección Integración del SDK D1 – Gestión de errores
        }
    }
}

// Para la versión de Android anterior a 4.4.0
fun checkCardDigitizationState_v2_4_0(d1Task: D1Task, cardID: String) {
    val d1PushWallet = d1Task.d1PushWallet
    val wallet = OEMPayType.GOOGLE_PAY // puede ser SAMSUNG_PAY

    val callback: D1Task.Callback<CardDigitizationState> = object : D1Task.Callback<CardDigitizationState> {

        override fun onSuccess(state: CardDigitizationState) {
            // Actualice la interfaz de usuario según el valor del estado

            // Ocultar botón "Añadir a Google/Samsung Pay"
            // Ocultar botón "Activar tu tarjeta"
            when (state) {
                NOT_DIGITIZED -> {
                    // Mostrar botón "Añadir a Google/Samsung Pay"
                }
                PENDING_IDV -> {
                    // 1. Mostrar botón "Activar tu tarjeta"
                    // 2. Autenticar al usuario final
                    // 3. Realizar activación: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }
                DIGITIZED -> {
                    // Ocultar botón "Añadir a Google/Samsung Pay"
                }
                else -> {
                    //No hacer nada
                }
            }
        }

        override fun onError(exception: D1Exception) {
            // Consulte la sección Integración del SDK D1 – Gestión de errores
        }
    }
    d1PushWallet.getCardDigitizationState(cardID, wallet, callback)
}

Use los últimos cuatro dígitos (recomendado)

El SDK D1 comprueba el estado de digitalización localmente en el dispositivo y no requiere una llamada de red. Esto reduce la latencia y mejora el rendimiento de la aplicación emisora.

// Para Android versión 4.4.0 y superior
fun checkCardDigitizationStateUsingLast4_v4_4_0(d1Task: D1Task, wallet: OEMPayType, last4: String) {
    activity.lifecycleScope.launch {
        try {
            val state = withContext(Dispatchers.IO) {
                d1Task.pushProvisioningService.getCardDigitizationState(wallet, last4).await()
            }
            // Actualice la interfaz de usuario según el valor del estado

            // Ocultar botón "Añadir a Google/Samsung Pay"
            // Ocultar botón "Activar tu tarjeta"
            when (state) {
                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.NOT_DIGITIZED -> {
                    // Mostrar botón "Añadir a Google/Samsung Pay"
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.PENDING_IDV -> {
                    // 1. Mostrar botón "Activar tu tarjeta"
                    // 2. Autenticar al usuario final
                    // 3. Realizar activación: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.DIGITIZED -> {
                    // Ocultar botón "Añadir a Google/Samsung Pay"
                }

                else -> {
                    //No hacer nada
                }
            }
        } catch (exception: D1Exception) {
            // Consulte la sección Integración del SDK D1 – Gestión de errores
        }
    }
}

iOS

En iOS, el SDK D1 devuelve un CardDigitizationResult objeto que incluye:

• el CardDigitizationState, y
• opcionales PKPass objetos (localPKPass y remotePKPass) que pueden usarse para mostrar información específica del dispositivo como deviceName.

Los estados posibles son:

• digitalizada La tarjeta ya está tokenizada. Ocultar Añadir a Apple Wallet.
• notDigitized Muestre un PKAddPassButton. Este estado se devuelve cuando al menos un dispositivo (por ejemplo, iPhone o Apple Watch emparejado) aún no está tokenizado.
• pendingIDVLocal / pendingIDVRemote La tokenización está pendiente de ID&V para el teléfono (pendingIDVLocal) o el reloj (pendingIDVRemote). Muestre un Activar en su teléfono/reloj botón, autentique al usuario final en la aplicación emisora y luego llame a activateDigitalCard().

Use la API que coincida con el identificador de tarjeta disponible en la aplicación emisora:

• Use D1Task.cardDigitizationState(_:) cuando tenga el cardID.
• Para D1 SDK v4.4.0 y versiones posteriores, use PushProvisioningService.cardDigitizationState(withLast4:) cuando solo tenga los últimos cuatro dígitos, por ejemplo, de los metadatos de la tarjeta.

Use card ID

import PassKit
let digitizeCardButton = PKAddPassButton()
let activateCardButton = UIButton(type: .system)
let cardID = "" // obtenido, por ejemplo, del servidor

// Para la versión de iOS 4.4.0 y superior
do {
    let service = try d1Task.pushProvisioningService()
    let result = try await service.cardDigitizationState(cardID)
    // Continúe con los flujos posteriores, por ejemplo, actualizar la interfaz de usuario
    switch result.state {
    case .pendingIDVLocal:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("Activar en su teléfono \(result.localPKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // después de autenticar al usuario final, se puede realizar la activación:
        // a partir de 4.5.0: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // antes de 4.5.0: self.d1Task.activateDigitalCard(cardID)
    case .pendingIDVRemote:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("Activar en su reloj \(result.remotePKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // después de autenticar al usuario final, se puede realizar la activación:
        // a partir de 4.5.0: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // antes de 4.5.0: self.d1Task.activateDigitalCard(cardID)
    case .notDigitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = false
    case .digitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = true
    }
} catch let d1Error as D1Error {
    // Consulte la sección Integración del SDK D1 – Gestión de errores
} catch let error {
    // Gestionar otro error
}

// Para la versión de iOS anterior a 4.4.0
d1Task.cardDigitizationState(cardID) { result, error in
    if let error = error {
        // Gestionar error
    } else if let result = result {
        // Continúe con los flujos posteriores, por ejemplo, actualizar la interfaz de usuario
        switch result.state {
        case .pendingIDVLocal:
            activateCardButton.isHidden = false
            activateCardButton.setTitle("Activar en su teléfono \(result.localPKPass?.deviceName ?? "")", for: .normal)
            digitizeCardButton.isHidden = true
            // después de autenticar al usuario final, se puede realizar la activación: self.d1Task.activateDigitalCard(cardID)
        case .pendingIDVRemote:
            activateCardButton.isHidden = false
            activateCardButton.setTitle("Activar en su reloj \(result.remotePKPass?.deviceName ?? "")", for: .normal)
            digitizeCardButton.isHidden = true
            // después de autenticar al usuario final, se puede realizar la activación: self.d1Task.activateDigitalCard(cardID)
        case .notDigitized:
            activateCardButton.isHidden = true
            digitizeCardButton.isHidden = false
        case .digitized:
            activateCardButton.isHidden = true
            digitizeCardButton.isHidden = true
        }
    }
}

Use los últimos cuatro dígitos (recomendado)

El SDK D1 comprueba el estado de digitalización localmente en el dispositivo y no requiere una llamada de red. Esto reduce la latencia y mejora el rendimiento de la aplicación emisora.

import PassKit

let digitizeCardButton = PKAddPassButton()
let activateCardButton = UIButton(type: .system)
let last4 = "" // obtenido, por ejemplo, de la API cardMetadata
do {
    let service = try d1Task.pushProvisioningService()
    let result = try await service.cardDigitizationState(withLast4: last4)
    // Continúe con los flujos posteriores, por ejemplo, actualizar la interfaz de usuario
    switch result.state {
    case .pendingIDVLocal:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("Activar en su teléfono \(result.localPKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // después de autenticar al usuario final, se puede realizar la activación:
        // a partir de 4.5.0: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // antes de 4.5.0: self.d1Task.activateDigitalCard(cardID)
    case .pendingIDVRemote:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("Activar en su reloj \(result.remotePKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // después de autenticar al usuario final, se puede realizar la activación:
        // a partir de 4.5.0: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // antes de 4.5.0: self.d1Task.activateDigitalCard(cardID)
    case .notDigitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = false
    case .digitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = true
    }
} catch let d1Error as D1Error {
    // Consulte la sección Integración del SDK D1 – Gestión de errores
} catch let error {
    // Gestionar otro error
}

Para ver todos los detalles del SDK D1, consulte la referencia de API.