Implement QR code payment

Overview

NFC Wallet SDK supports QR code payments for Thales white-label EMV PURE cards only.

Before you implement QR code payments, complete Tokenization. See Tokenize a card.

SDK Integration

Check prerequisites

Confirm the digital card supports QR code payments using DigitalCard.Details.isPaymentTypeSupported() with PaymentType.qr.

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

Create the QR payment input data

Create QRPaymentSession.QRPaymentInputData. It contains the transaction parameters used to build the QR code payment payload.

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 has the following fields:

Input data	Format	Length	Description
aid	Hexadecimal ISO/IEC 7816-5	10 to 32 characters	Mandatory Use "0000000000" to let the SDK use the primary AID.
amount	BCD-encoded hexadecimal	12 characters	Mandatory Transaction amount in BCD format. An amount of 5.22 EUR has the value “000000000522”.
currencyCode	ISO-4217 numeric string	4 characters	Mandatory Transaction currency. Use "0978" for EUR.
idd	Hexadecimal	30 characters	Optional Issuer-specific data

Generate QR payment data

In your digital wallet application, call generateQRPaymentData to generate the payload to encode in a QR code.

This API can throw an error. See Handle errors.

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

Parameter	Description
statusWord	Transaction status word. 9000 indicates success. See Handle status word
cid	Cryptogram Information Data. Determines if a CDCVM is required for this transaction.
chipDataField	Chip data field computed by NFC including the cryptogram.
condensedPaymentData	Not applicable
cardMainAid	The main AID for the card that is used for the payment.
cardMainAppTemplate	The main Application Template of the card that is used for payment.
cardAliasAid	The alternate AID of the card that is used for payment.
cardAliasAppTemplate	The alternate Application Template of the card that is used for payment.
commonDataTemplate	The Common Data Template calculated during the payment.

You can use a non-default digital card for the QR code payment by passing digitalCardID to generateQRPaymentData.

Handle status word

Always check statusWord before using any other field.

• 9000 indicates a successful payload generation. You can read the other fields in QRPaymentOutputData.

• Other values indicate a failure. Do not use the other fields in QRPaymentOutputData.

See table below for more details:

Status word value	Description
9000	A successful transaction. All fields in the QRPaymentOutputData object are available to fetch if the cid value is 0x8x. Where: The first digit indicates "Request to process the transaction online". The second digit indicates the CVM information such as No CVM Required, Local CDCVM entered, Local CDCVM required and so on. If the CID is not in the 0x8x format, the fields are empty.
6989	Customer verification required due to CIAC values and no method is defined in Application Control.
6988	Zero transaction amount is not allowed.
6987	Transaction amount exceeds the card issuer defined limit.
6986	Transaction amount exceeds the consumer defined limit.
6985	ATC limit reached or the selected AID is not referring to a payment application that is compliant to this specification.

Handle errors

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

Error	Description
deviceEnvironmentUnsafe	The device does not meet the security requirements.
sessionInProgress	Another payment session is still running.
unsupportedPaymentType	The digital card does not support QR code payment.
invalidQRInputData	One or more fields in QRPaymentInputData are missing or malformed.
qrPaymentFailed	The payload cannot be generated due to an internal failure.
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.

NFC Wallet SDK automatically wipes stored credentials when authenticationKeyInvalidated occurs (for example, after a passcode reset or security change).

Your application should guide the end user through re-enrollment.

Full implementation example

Use this code sample to understand how the previous steps fit together.

func generateOutputData(digitalCard: DigitalCard?) async -> QRPaymentSession.QRPaymentOutputData? {
    do {
        let paymentSession = QRPaymentSession()
        // Use your maximum amount for QR code payments, if applicable.
        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 {
            // QR code payment with default card
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, userPrompt: "Authenticate")
        } else {
            // QR code payment with provided digital card
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, digitalCardID: digitalCard?.digitalCardID, userPrompt: "Authenticate")
        }
        
    } catch {
        // Handle 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
    }
}

Generate and display QR code image

Your digital wallet application is responsible for generating and displaying the QR code image using the output returned by the NFC Wallet SDK.

After you receive QRPaymentOutputData for a QR code payment, your digital wallet application must:

1. Build the QR code payload.

2. Generate the QR code image.

3. Display the QR code image for the end user to present at the POS.

iOS supports QR code generation natively (Core Image).