Implementar pago con código QR

Descripción general

NFC Wallet SDK solo admite pagos con código QR para tarjetas Thales white-label EMV PURE.

Antes de implementar pagos con código QR, complete Tokenización. Consulte Tokenizar una tarjeta.

Integración del SDK

Comprueba los requisitos previos

Confirme que la tarjeta digital admite pagos con código QR usando DigitalCard.Details.isPaymentTypeSupported() con PaymentType.qr.

func checkCardSupportForQR(card: DigitalCard) async throws -> Bool {
    return try await card.details.isPaymentTypeSupported(.qr)
}

Cree los datos de entrada del pago QR

Cree QRPaymentSession.QRPaymentInputData. Contiene los parámetros de la transacción utilizados para construir la carga útil del pago con código QR.

let amount   = "000000500030"  // 5000.30 EUR
let currency = "0978" // EUR
let aid      = "00000000000000000000000000000000"    // 16 bytes long
let idd      = "000000000000000000000000000000"      // 15 bytes long
let inputData = QRPaymentSession.QRPaymentInputData(amount: amount, currencyCode: currency, aid: aid, idd: idd)

QRPaymentSession.QRPaymentInputData tiene los siguientes campos:

Datos de entrada	Formato	Longitud	Descripción
aid	Hexadecimal ISO/IEC 7816-5	10 a 32 caracteres	Obligatorio Use "0000000000" para permitir que el SDK use el AID principal.
amount	hexadecimal codificado en BCD	12 caracteres	Obligatorio Importe de la transacción en formato BCD. Un importe de 5.22 EUR tiene el valor “000000000522”.
currencyCode	ISO-4217 cadena numérica	4 caracteres	Obligatorio Moneda de la transacción. Use "0978" para EUR.
idd	Hexadecimal	30 caracteres	Opcional Datos específicos del emisor

Generar datos de pago QR

En su aplicación de billetera digital, llame a generateQRPaymentData para generar la carga útil que se codificará en un código QR.

Esta API puede generar un error. Consulte Maneja los errores.

Si tiene éxito, la API devuelve QRPaymentOutputData con los siguientes campos:

Parámetro	Descripción
statusWord	Palabra de estado de la transacción. 9000 indica éxito. Consulte Manejar la palabra de estado
cid	Datos de información del criptograma. Determina si se requiere un CDCVM para esta transacción.
chipDataField	Campo de datos del chip calculado por NFC, incluido el criptograma.
condensedPaymentData	No aplicable
cardMainAid	El AID principal de la tarjeta que se usa para el pago.
cardMainAppTemplate	La plantilla principal de aplicación de la tarjeta que se usa para el pago.
cardAliasAid	El AID alternativo de la tarjeta que se usa para el pago.
cardAliasAppTemplate	La plantilla de aplicación alternativa de la tarjeta que se usa para el pago.
commonDataTemplate	La plantilla de datos comunes calculada durante el pago.

Puede usar una tarjeta digital que no sea la predeterminada para el pago con código QR pasando digitalCardID en generateQRPaymentData.

Manejar la palabra de estado

Compruebe siempre statusWord antes de usar cualquier otro campo.

• 9000 indica una generación correcta de la carga útil. Puede leer los demás campos en QRPaymentOutputData.
• Otros valores indican un fallo. No use los demás campos en QRPaymentOutputData.

Consulte la tabla siguiente para obtener más detalles:

Valor de la palabra de estado	Descripción
9000	Una transacción exitosa. Todos los campos del QRPaymentOutputData objeto están disponibles para obtenerlos si el cid valor es 0x8x. Donde: El primer dígito indica "Solicitud para procesar la transacción en línea". El segundo dígito indica la información CVM, como No CVM Required, Local CDCVM entered, Local CDCVM required, etc. Si el CID no está en el formato 0x8x, los campos están vacíos.
6989	Se requiere verificación del cliente debido a valores CIAC y no se define ningún método en Application Control.
6988	No se permite un importe de transacción cero.
6987	El importe de la transacción supera el límite definido por el emisor de la tarjeta.
6986	El importe de la transacción supera el límite definido por el consumidor.
6985	Se alcanzó el límite ATC o el AID seleccionado no hace referencia a una aplicación de pago que cumpla con esta especificación.

Maneja los errores

Si generateQRPaymentData lanza un error, considere que el pago ha fallado. Restablezca el estado de su interfaz. Guíe al usuario final hacia la siguiente mejor acción.

Error	Descripción
deviceEnvironmentUnsafe	El dispositivo no cumple los requisitos de seguridad.
sessionInProgress	Otra sesión de pago aún se está ejecutando.
unsupportedPaymentType	La tarjeta digital no admite pagos con código QR.
invalidQRInputData	Uno o más campos en QRPaymentInputData faltan o tienen un formato incorrecto.
qrPaymentFailed	No se puede generar la carga útil debido a un fallo interno.
authenticationKeyInvalidated	Se deshabilitó el código de acceso del dispositivo y el almacenamiento seguro se borró.
biometricNotEnrolled	La biometría no está disponible o no está registrada.

Cada error puede incluir un mensaje que explique el fallo. Úselo para la solución de problemas y el diagnóstico de soporte.

NFC Wallet SDK borra automáticamente las credenciales almacenadas cuando authenticationKeyInvalidated ocurre (por ejemplo, después de restablecer el código de acceso o de un cambio de seguridad).

Su aplicación debe guiar al usuario final durante el proceso de re-registro.

Ejemplo completo de implementación

Use esta muestra de código para entender cómo encajan los pasos anteriores.

func generateOutputData(digitalCard: DigitalCard?) async -> QRPaymentSession.QRPaymentOutputData? {
    do {
        let paymentSession = QRPaymentSession()
        // Use su importe máximo para los pagos con código QR, si corresponde.
        let amount   = "000000000000"
        let currency = "0000"
        let aid      = "00000000000000000000000000000000"
        let idd      = "000000000000000000000000000000"
        let inputData = QRPaymentSession.QRPaymentInputData(amount: amount, currencyCode: currency, aid: aid, idd: idd)
        
        if let digitalCard = digitalCard, try await digitalCard.isDefaultCard {
            // Pago con código QR con la tarjeta predeterminada
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, userPrompt: "Autenticar")
        } else {
            // Pago con código QR con la tarjeta digital proporcionada
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, digitalCardID: digitalCard?.digitalCardID, userPrompt: "Autenticar")
        }
        
    } catch {
        // Gestionar el error
        if let error = error as? QRPaymentSession.Error {
            switch error {
            case.deviceEnvironmentUnsafe(_): break
            case .sessionInProgress: break
            case .unsupportedPaymentType(_): break
            case .invalidQRInputData(_): break
            case .qrPaymentFailed(_): break
            case .authenticationKeyInvalidated(_): break
            case .biometricNotEnrolled(_): break
            @unknown default:
                break
            }
        } else {
            //
        }
        return nil
    }
}

Generar y mostrar la imagen del código QR

Su aplicación de monedero digital es responsable de generar y mostrar la imagen del código QR usando la salida devuelta por NFC Wallet SDK.

Después de recibir QRPaymentOutputData para un pago con código QR, su aplicación de monedero digital debe:

1. Construir la carga útil del código QR.
2. Generar la imagen del código QR.
3. Mostrar la imagen del código QR para que el usuario final la presente en el POS.

iOS admite de forma nativa la generación de códigos QR (Core Image).