Implementar el pago con código QR

Resumen

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

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

Integración del SDK

Compruebe los requisitos previos

Confirme que la tarjeta digitalizada admite pagos con código QR usando DigitalizedCardDetails.paymentTypeSupported(). Esta API devuelve una lista de tipos de pago compatibles. Verifique que PaymentType.QR está presente.

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

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

Cree los datos de entrada del pago con QR

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

Use PaymentInputData.PaymentInputBuilder con:

• withQRCodePaymentParameters para proporcionar importe, currencyCode y countryCode
• withPureQRCodePaymentParameters para proporcionar idd (iddData) y aid (aidData)

Use los siguientes valores de ejemplo como marcadores de posición.

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 para código QR tiene los siguientes campos.

Campo	Formato	Longitud	Requisito	Descripción
aid	Hexadecimal (ISO/IEC 7816-5)	De 5 a 16 bytes	Requerido	Use "0000000000" para permitir que el SDK use el AID principal.
importe	Hexadecimal codificado en BCD	6 bytes	Requerido	Importe de la transacción en formato BCD. Ejemplo: 5,22 EUR es "000000000522".
currencyCode	Numérico 3 (ISO-4217)	3 caracteres	Requerido	Moneda de la transacción. Por ejemplo, use "978" para EUR.
countryCode	Numérico 3 (ISO 3166-1)	3 caracteres	Requerido	Código de país de la transacción.
idd	Hexadecimal	15 bytes	Opcional	Datos específicos del emisor.

Genere los datos de pago con QR

En su aplicación de billetera digital, llame a PaymentBusinessService.generateApplicationCryptogram() usando el tipo de pago PaymentType.QR para generar la carga útil que se codificará en un código QR.

Debe implementar un QRCodePaymentServiceListener.

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

Implemente QRCodePaymentServiceListener

El listener del código QR gestiona los eventos durante la generación del código QR.

El listener del código QR tiene cuatro callbacks:

• onAuthenticationRequired

  El SDK indica que se requiere verificación CDCVM. Consulte Realizar verificación CDCVM.
• onDataReadyForPayment

  Los datos de salida del código QR están listos.
• onError

  El SDK ha encontrado un fallo durante el pago con código QR.
• onNextTransactionReady

  El SDK ha finalizado la desactivación del servicio de pago. Este callback solo se activa después de que se complete la generación del código QR. Úselo para recuperar el estado de desactivación y comprobar el estado de la tarjeta digitalizada.

El siguiente fragmento de código muestra una implementación básica del listener:

QRCodePaymentServiceListener l = new QRCodePaymentServiceListener() {

    @Override
    public void onDataReadyForPayment(PaymentService paymentService,TransactionContext transactionContext) {
        //El pago se ha procesado y se ha completado correctamente.


        //Recupere los datos de salida del código QR generados por el SDK
        //para que la MPA construya la carga útil y genere el símbolo del código QR
        QRCodeData qrCodeData = paymentService.getQRCodeData();

        // Lógica para mostrar el código QR en la pantalla
    }

    @Override
    public void onAuthenticationRequired(PaymentService activatedPaymentService, CHVerificationMethod cvm, long cvmResetTimeout)
        //El SDK solicita que se realice una verificación CVM.

        if (chVerificationMethod == CHVerificationMethod.DEVICE_KEYGUARD) {
            // Lógica para usar el bloqueo del dispositivo para la verificación CVM
        } else if (chVerificationMethod == CHVerificationMethod.BIOMETRICS) {
            // Lógica para usar la biometría para la verificación CVM
        }

    }

    @Override
    public void onError(TransactionContext transactionContext, PaymentServiceErrorCode paymentServiceErrorCode, String s) {
        // Lógica para gestionar un error durante el pago.
    }

		@Override
    public void onNextTransactionReady(DeactivationStatus deactivationStatus, DigitalizedCardStatus digitalizedCardStatus, DigitalizedCard        		digitalizedCard) {
        // El proceso de desactivación del servicio de pago ha finalizado.
      	//Recupere el estado de desactivación
      if (deactivationStatus.getSdkStatusCode() == DEACTIVATION_SUCCESS) {
           // El proceso de desactivación ha finalizado correctamente. Listo para realizar el siguiente pago.
      else{
          // El proceso de desactivación ha fallado.
         	// Compruebe si es necesario reponer.
          if (digitalizedCardStatus.needsReplenishment())
          {
               // lógica para activar el proceso de reposición.
          }else{
              // lógica para activar el restablecimiento de la tarjeta predeterminada.
          }
      }
    }

Obtenga los datos de pago con QR

Obtener QRCodeData cuando QRCodePaymentServiceListener.onDataReadyForPayment() se activa.

QRCodeData contiene los siguientes campos.

Campo	Descripción
statusWord	Palabra de estado de la transacción. 9000 indica éxito. Consulte Gestión de la palabra de estado.
cid	Datos de información del criptograma. Determina si CDCVM es necesario para esta transacción.
chipDataField	Campo de datos del chip calculado por NFC, incluido el criptograma.
condensedPaymentData	No aplicable.
cardMainAid	AID principal utilizado para el pago.
cardMainAppTemplate	Plantilla principal de la aplicación utilizada para el pago.
cardAliasAid	AID alternativo utilizado para el pago.
cardAliasAppTemplate	Plantilla alternativa de la aplicación utilizada para el pago.
commonDataTemplate	Plantilla de datos comunes calculada durante el pago.

Gestión de 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 QRCodeData.
• Otros valores indican un fallo. No use los demás campos en QRCodeData.

Consulte la tabla siguiente para más detalles:

Valor de la palabra de estado	Descripción
9000	Una transacción exitosa. Todos los campos del QRCodeData objeto están disponibles 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 información CVM, como Sin CVM requerida, CDCVM local introducida, y así sucesivamente. Si el CID no está en el formato 0x8x, los campos están vacíos.
6989	Se requiere verificación del cliente 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 supera el límite definido por el emisor.
6986	El importe de la transacción supera el límite definido por el usuario final.
6985	Se ha alcanzado el límite ATC, o el AID seleccionado no se refiere a una aplicación de pago compatible con esta especificación.

Gestione los errores

Cuando se llame a QRCodePaymentServiceListener#onError(…) la función, se proporcionarán un código de error y un mensaje.

Si los datos de entrada son nulos, están vacíos o el listener no es una instancia de QRCodePaymentServiceListener, se lanzará una IllegalArgumentException con un mensaje.

La siguiente tabla muestra los códigos de error del código QR:

Código de error	Descripción	Acción recomendada
NO_DEFAULT_CARD	No hay ninguna tarjeta predeterminada configurada.	Configure una tarjeta predeterminada antes de iniciar un pago con código QR.
QR_CODE_PAYMENT_NOT_SUPPORTED	La tarjeta predeterminada no admite pagos con código QR.	Llamar a DigitalizedCardDetails#paymentTypeSupported() y verifique PaymentType.QR está presente.
QR_CODE_WRONG_STATE	El servicio de pago ya está activado cuando inicia un pago con código QR.	Si el usuario final cancela CDCVM, llame a PaymentBusinessService#deactivate().
QR_CODE_INPUT_INVALID	Los datos de entrada están presentes, pero uno o más campos no son válidos.	Proporcione datos de entrada válidos e incluya todos los campos requeridos. El SDK valida la estructura JSON, los valores hexadecimales, los rangos de valores y las longitudes de los campos.
QR_CODE_OUTPUT_INVALID	Los datos de salida no se pueden analizar y no están disponibles.	Trate el pago con código QR como fallido y no muestre el código QR.
CARD_OUT_OF_PAYMENT_KEYS	No hay credenciales de pago disponibles.	Reponga las credenciales antes de intentar otro pago.

Genere y muestre la imagen del código QR

Su aplicación de billetera digital genera la carga útil del código QR usando los datos proporcionados por el NFC Wallet SDK.

Después de generar los datos de pago con código QR, su aplicación de billetera digital debe:

• Construir un símbolo de carga útil usando uno de los criptogramas generados por el SDK.
• Codificar en Base64.
• Mostrar el símbolo del código QR.

Hay varias bibliotecas disponibles, como la biblioteca ZXing, para renderizar el código QR.

Su aplicación de billetera digital puede elegir el nivel de corrección (L, M, Q, H) para ajustar la corrección de errores.