Implementar pago mediante código QR

Resumen

El SDK de NFC Wallet admite pagos con código QR solo para tarjetas EMV PURE de marca blanca de Thales.

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

Integración del SDK

Comprobar 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)
}

Crear los datos de entrada de pago QR

Crear QRPaymentSession.QRPaymentInputData. Contiene los parámetros de la transacción utilizados para construir la carga útil del pago por QR.

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

QRPaymentSession.QRPaymentInputData has the following fields:

Input data	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 primario.
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

In your digital wallet application, call generateQRPaymentData para generar la carga útil que se codificará en un código QR.

This API can throw an error. See Manejar errores.

On success, the API returns QRPaymentOutputData with the following fields:

Parámetro	Descripción
statusWord	Palabra de estado de la transacción. 9000 indica éxito. Vea Manejar palabra de estado
cid	Datos de Información de Criptograma. Determina si se requiere CDCVM para esta transacción.
chipDataField	Campo de datos del chip calculado por NFC que incluye el criptograma.
condensedPaymentData	No aplicable
cardMainAid	El AID principal de la tarjeta que se utiliza para el pago.
cardMainAppTemplate	La Plantilla de Aplicación principal de la tarjeta que se utiliza para el pago.
cardAliasAid	El AID alternativo de la tarjeta que se utiliza para el pago.
cardAliasAppTemplate	La Plantilla de Aplicación alternativa de la tarjeta que se utiliza para el pago.
commonDataTemplate	La Plantilla de Datos Comunes calculada durante el pago.

Puede usar una tarjeta digital no predeterminada para el pago con código QR pasando digitalCardID a generateQRPaymentData.

Manejar palabra de estado

Siempre verifique statusWord antes de usar cualquier otro campo.

• 9000 indica una generación de carga útil exitosa. Puede leer los otros campos en QRPaymentOutputData.

• Otros valores indican un fallo. No use los otros campos en QRPaymentOutputData.

Consulte la tabla a continuación para más detalles:

Valor de la palabra de estado	Descripción
9000	Una transacción exitosa. Todos los campos en el QRPaymentOutputData objeto están disponibles para obtener si el cid valor es 0x8x. Donde: El primer dígito indica "Solicitud de procesar la transacción en línea". El segundo dígito indica la información CVM como Sin CVM requerido, CDCVM local introducido, CDCVM local requerido, etc. Si el CID no está en el formato 0x8x, los campos están vacíos.
6989	Verificación del cliente requerida debido a los valores CIAC y no se define ningún método en el Control de Aplicación.
6988	No se permite un importe de transacción cero.
6987	El importe de la transacción excede el límite definido por el emisor de la tarjeta.
6986	El importe de la transacción excede el límite definido por el consumidor.
6985	Límite de ATC alcanzado o el AID seleccionado no se refiere a una aplicación de pago que cumpla esta especificación.

Manejar errores

If generateQRPaymentData throws an error, treat the payment as failed. Reset your UI state. Guide the end user to the next best action.

Error	Descripción
deviceEnvironmentUnsafe	The device does not meet the security requirements.
sessionInProgress	Another payment session is still running.
unsupportedPaymentType	La tarjeta digital no admite el pago con código QR.
invalidQRInputData	One or more fields in QRPaymentInputData are missing or malformed.
qrPaymentFailed	La carga útil no se puede generar debido a una falla interna.
authenticationKeyInvalidated	The device passcode was disabled and secure storage was wiped.
biometricNotEnrolled	Biometrics are unavailable or not enrolled.

Each error can include a message that explains the failure. Use it for troubleshooting and support diagnostics.

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

Su aplicación debe guiar al usuario final a través del re-registro.

Full implementation example

Use este ejemplo 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 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: "Authenticate")
        } else {
            // Pago con código QR con la tarjeta digital proporcionada
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, digitalCardID: digitalCard?.digitalCardID, userPrompt: "Authenticate")
        }
        
    } catch {
        // Manejar 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 billetera digital es responsable de generar y mostrar la imagen del código QR usando la salida devuelta por el SDK de NFC Wallet.

Después de recibir QRPaymentOutputData para un pago con código QR, su aplicación de billetera 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 punto de venta.

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