Reponer claves de pago

Resumen

Se requieren claves de pago para calcular criptogramas EMV para pagos sin contacto.

En un modelo de emulación de tarjeta en el host (HCE), las claves de pago son temporales. Renuévalas antes de que se agoten para evitar interrupciones en los pagos.

Esta guía cubre cuándo renovarlas y cómo activarlo.

El SDK de NFC Wallet admite varios tipos de claves de pago:

• SUK (Clave de un solo uso): Una clave de pago de un solo uso utilizada para cada transacción individual. Aplicable para Mastercard y Thales EMV White Label (PURE).
• LUK (Clave de uso limitado): Una clave de pago que puede usarse para múltiples transacciones antes de expirar. Aplicable para Visa.

Requisitos previos

Configurar umbrales de renovación (incorporación)

Configura los umbrales de renovación durante la incorporación con el equipo de entrega de Thales.

Al definir los umbrales, considera:

• SUK: la cantidad restante de SUK que debería activar la renovación.
• LUK: la cantidad restante de transacciones y el tiempo de expiración de la LUK.

Integración del SDK

Detectar cuándo se requiere renovación

Usa una (o ambas) de estas señales:

• Comprobación proactiva: lee DigitalCard.PaymentKeyInfo.needsReplenishment.
• Push reactivo (activado por el TSP): procesa MG:ReplenishmentNeededNotification notificaciones push del TSP.

Para la entrega y el enrutamiento de las notificaciones push, consulta Gestionar notificaciones push.

Comprobación proactiva

Comprueba regularmente cada tarjeta digital, por ejemplo después de cada pago o al iniciar la aplicación.

func checkReplenishment(digitalCard: DigitalCard) async throws -> Bool {
    return try await digitalCard.paymentKeyInfo.needsReplenishment
}

Realiza esta comprobación proactiva:

• Después de SDK de NFC Wallet inicialización.
• Después de un pago.
• Cuando la tarjeta se establece como predeterminada.
• Después de que se recupere la conectividad (sin conexión → en línea).

Activa la renovación tan pronto como el SDK indique que es necesaria. Evita cerrar la aplicación mientras la renovación está en curso.

Activar renovación

Llama a ReplenishmentService.replenish(digitalCardID:) cuando decidas renovarla.

func replenishment(digitalCard: DigitalCard) async {
    do {
        if try await digitalCard.paymentKeyInfo.needsReplenishment {
            let replenishmentService = ReplenishmentService()
            try await replenishmentService.replenish(digitalCardID: digitalCard.digitalCardID)
         
            // El backend de NFC Wallet envía una notificación push para confirmar la operación.
            // Tu aplicación debe procesarla. Consulta "Gestionar notificaciones push".
        }
    } catch let error {
        switch (error as? ReplenishmentService.Error) {
            case .networkError:
                break
            case .missingWalletSecureEnrollment:
                break
            case .deviceEnvironmentUnsafe(let error):
                break
            case .clientError(let message):
                break
            case .serverError(let message):
                break
            case .unknown(let underlying):
                break
            @unknown default:
                break
        }
    }
}

Después de enviar la solicitud de renovación, el backend de NFC Wallet envía una notificación push. Tu aplicación la procesa y el SDK recupera las nuevas claves de pago.

Activado por el TSP Cuando recibas MG:ReplenishmentNeededNotificationllama a ReplenishmentService.replenish(digitalCardID:isForced:) con isForced: true.

Consulta Procesar notificaciones de MG (renovación).