Implement QR Code payment

Overview

The 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 digitized card supports QR code payments using DigitalizedCardDetails.paymentTypeSupported(). This API returns a list of supported payment types. Verify that PaymentType.QR is present.

public boolean isQRCodeSupported(DigitalizedCardDetails card) {
    final PaymentType[] supported = card.paymentTypeSupported();

    for (PaymentType p : supported) {
        if (p == PaymentType.QR) {
            return true;
        }
    }
    return false;
}

Create the QR payment input data

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

Use PaymentInputData.PaymentInputBuilder with:

• withQRCodePaymentParameters to provide amount, currencyCode and countryCode
• withPureQRCodePaymentParameters to provide idd (iddData) and aid (aidData)

Use the following sample values as placeholders.

String QR_NOMINAL_VALID_AID = “0000000000”;
String QR_NOMINAL_VALID_AMOUNT =  “000000000500”;
char currencyCode = 789;
String QR_NOMINAL_VALID_IDD = “000000000000000000000000000000”;

PaymentInputData paymentInputData = new PaymentInputData.PaymentInputBuilder(PaymentType.QR)
                .withQRCodePaymentParameters(QR_NOMINAL_VALID_AMOUNT, QR_NOMINAL_VALID_CURRENCY, (char)0)
                .withPureQRCodePaymentParameters(QR_NOMINAL_VALID_IDD.getBytes(), QR_NOMINAL_VALID_AID.getBytes())
                .build();

PaymentInputData for QR code has the following fields.

Field	Format	Length	Requirement	Description
aid	Hexadecimal (ISO/IEC 7816-5)	5 to 16 bytes	Required	Use "0000000000" to let the SDK use the primary AID.
amount	BCD-encoded hexadecimal	6 bytes	Required	Transaction amount in BCD format. Example: 5.22 EUR is "000000000522".
currencyCode	Numeric 3 (ISO-4217)	3 characters	Required	Transaction currency. Example: use "978" for EUR.
countryCode	Numeric 3 (ISO 3166-1)	3 characters	Required	Transaction country code.
idd	Hexadecimal	15 bytes	Optional	Issuer-specific data.

Generate QR payment data

In your digital wallet application, call PaymentBusinessService.generateApplicationCryptogram() using payment type PaymentType.QR to generate the payload to encode in a QR code.

You must implement a QRCodePaymentServiceListener.

final PaymentBusinessService pbs = PaymentBusinessManager.getPaymentBusinessService();
pbs.generateApplicationCryptogram(
        PaymentType.QR, 
        paymentInputData, 
        qrCodePaymentServiceListener);

Implement QRCodePaymentServiceListener

The QR code listener handles events during QR code generation.

The QR code listener has four callbacks:

• onAuthenticationRequired

  The SDK indicates CDCVM verification is required. See Perform CDCVM verification.
• onDataReadyForPayment

  QR code output data is ready.
• onError

  The SDK has encountered a failure during the QR code payment.
• onNextTransactionReady

  The SDK has finished payment service deactivation. This callback is only triggered after QR code generation completes. Use it to retrieve the deactivation status and check the digitized card state.

The following code snippet shows a basic implementation of the listener:

QRCodePaymentServiceListener l = new QRCodePaymentServiceListener() {

    @Override
    public void onDataReadyForPayment(PaymentService paymentService,TransactionContext transactionContext) {
        //The Payment has been processed and is succesful.


        //Retrieve the QR Code output data generated by the SDK
        //in order for the MPA to build the payload and generate the QR code symbol
        QRCodeData qrCodeData = paymentService.getQRCodeData();

        // Logic to display the QR Code on the screen
    }

    @Override
    public void onAuthenticationRequired(PaymentService activatedPaymentService, CHVerificationMethod cvm, long cvmResetTimeout)
        //The SDK requests a CVM Verification to be done.

        if (chVerificationMethod == CHVerificationMethod.DEVICE_KEYGUARD) {
            // Logic to use the Device Keyguard for CVM Verification
        } else if (chVerificationMethod == CHVerificationMethod.BIOMETRICS) {
            // Logic to use the Biometrics for CVM Verification
        }

    }

    @Override
    public void onError(TransactionContext transactionContext, PaymentServiceErrorCode paymentServiceErrorCode, String s) {
        // Logic to handle an error during the payment.
    }

		@Override
    public void onNextTransactionReady(DeactivationStatus deactivationStatus, DigitalizedCardStatus digitalizedCardStatus, DigitalizedCard        		digitalizedCard) {
        // Payment service deactivation process is finish.
      	//Retrieve Deactivation Status
      if (deactivationStatus.getSdkStatusCode() == DEACTIVATION_SUCCESS) {
           // Deativation process is finish successfully. Ready to do next payment.
      else{
          // Deativation process is failed.
         	// Check Replishment is needed.
          if (digitalizedCardStatus.needsReplenishment())
          {
               // logic trigger replenishment process.
          }else{
              // logic trigger reset default card.
          }
      }
    }

Get QR payment data

Get QRCodeData when QRCodePaymentServiceListener.onDataReadyForPayment() is triggered.

QRCodeData contains the following fields.

Field	Description
statusWord	Transaction status word. 9000 indicates success. See Handle status word.
cid	Cryptogram Information Data. Determines if CDCVM is required for this transaction.
chipDataField	Chip data field computed by NFC, including the cryptogram.
condensedPaymentData	Not applicable.
cardMainAid	Main AID used for the payment.
cardMainAppTemplate	Main application template used for the payment.
cardAliasAid	Alternate AID used for the payment.
cardAliasAppTemplate	Alternate application template used for the payment.
commonDataTemplate	Common data template calculated during the payment.

Handle status word

Always check statusWord before using any other field.

• 9000 indicates a successful payload generation. You can read the other fields in QRCodeData.
• Other values indicate a failure. Do not use the other fields in QRCodeData.

See table below for more details:

Status word value	Description
9000	A successful transaction. All fields in the QRCodeData object are available if the cid value is 0x8x. Where: The first digit indicates \"Request to process the transaction online\". The second digit indicates CVM information such as No CVM Required, Local CDCVM entered, and so on. If the CID is not in the 0x8x format, the fields are empty.
6989	Customer verification is 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 issuer-defined limit.
6986	Transaction amount exceeds the end user-defined limit.
6985	ATC limit is reached, or the selected AID does not refer to a payment application that is compliant with this specification.

Handle errors

When the QRCodePaymentServiceListener#onError(…) function is called, an error code and a message will be provided.

If the input data is null, empty, or the listener is not an instance of QRCodePaymentServiceListener, an IllegalArgumentException will be thrown with a message.

The following table shows the QR code error codes:

Error code	Description	Recommended action
NO_DEFAULT_CARD	No default card is set.	Set a default card before you initiate a QR code payment.
QR_CODE_PAYMENT_NOT_SUPPORTED	The default card does not support QR code payments.	Call DigitalizedCardDetails#paymentTypeSupported() and verify PaymentType.QR is present.
QR_CODE_WRONG_STATE	The payment service is already activated when you start a QR code payment.	If the end user cancels CDCVM, call PaymentBusinessService#deactivate().
QR_CODE_INPUT_INVALID	Input data is present, but one or more fields are invalid.	Provide valid input data and include all required fields. The SDK validates JSON structure, hexadecimal values, value ranges, and field lengths.
QR_CODE_OUTPUT_INVALID	Output data cannot be parsed and is not available.	Treat the QR code payment as failed and do not display the QR code.
CARD_OUT_OF_PAYMENT_KEYS	No payment credentials are available.	Replenish credentials before attempting another payment.

Generate and display QR code image

Your digital wallet application generates the QR code payload using the data provided by the NFC Wallet SDK.

After you generate the QR code payment data, your digital wallet application must:

• Build a payload symbol using one of the cryptograms generated by the SDK.
• Encode in Base64.
• Display the QR code symbol.

Several libraries are available, such as the ZXing library, to render the QR code.

Your digital wallet application can choose the correction level (L, M, Q, H) to fine-tune error correction.