Reponer claves de pago

Resumen

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

En un modelo de Host Card Emulation (HCE), las claves de pago son temporales. Renuévalas antes de que se agoten para evitar interrupciones en los pagos.

Esta guía explica cuándo reponer y cómo desencadenar la reposición.

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

• SUK (Clave de Uso Único): 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 se puede usar en múltiples transacciones antes de que caduque. Aplicable para Visa.

Requisitos previos

Configurar umbrales de reposición (onboarding)

Configure los umbrales de reposición durante el onboarding con el equipo de entrega de Thales.

Al definir los umbrales, tenga en cuenta:

• SUK: el recuento restante de SUK que debería desencadenar la reposición.

• LUK: el recuento de transacciones restantes y el tiempo de expiración de la LUK.

Integración del SDK

Detectar cuándo se requiere reposición

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

• Verificación proactiva: leer DigitalCard.PaymentKeyInfo.needsReplenishment.

• Push reactivo (disparado por TSP): procesar MG:ReplenishmentNeededNotification notificaciones push desde el TSP.

Para la entrega y el enrutamiento de push, vea Manejar notificaciones push.

Verificación proactiva

Verifique regularmente para 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
}

Realice esta verificación proactiva:

• Después de inicialización del SDK de NFC Wallet .

• Después de un pago.

• Cuando la tarjeta se establece como predeterminada.

• Después de que vuelva la conectividad (offline → online).

Active la reposición tan pronto como el SDK indique que es necesaria. Evite terminar la aplicación mientras la reposición esté en progreso.

Activar la reposición

Llame a ReplenishmentService.replenish(digitalCardID:) cuando decida reponer.

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.
            // Su aplicación debe procesarla. Vea "Manejar 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 reposición, el backend de NFC Wallet envía una notificación push. Su aplicación la procesa y el SDK recupera las nuevas claves de pago.

Disparado por TSP Cuando reciba MG:ReplenishmentNeededNotificationllame a ReplenishmentService.replenish(digitalCardID:isForced:) con isForced: true.

Vea Procesar notificaciones MG (reposición).