QRコード支払いを実装する

概要

NFC Wallet SDK は Thales のホワイトラベル EMV PURE カード専用の QR コード決済をサポートします。

QR コード決済を実装する前に、次を完了してください トークナイゼーション。参照してください カードをトークン化する.

SDK 統合

前提条件を確認する

デジタル化されたカードが次を使用して QR コード決済をサポートしていることを確認します DigitalizedCardDetails.paymentTypeSupported()。この API はサポートされている支払いタイプの一覧を返します。次を確認してください PaymentType.QR が存在すること。

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

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

QR 支払いの入力データを作成する

作成 PaymentInputData。これは QR コード支払いペイロードを構築するために使用されるトランザクションパラメータを含みます。

使用する PaymentInputData.PaymentInputBuilder に対して：

• withQRCodePaymentParameters を提供するために amount, currencyCode と countryCode

• withPureQRCodePaymentParameters を提供するために idd (iddData) と aid (aidData)

次のサンプル値をプレースホルダとして使用してください。

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 QR コードには次のフィールドがあります。

フィールド	フォーマット	長さ	要件	説明
aid	16 進数 (ISO/IEC 7816-5)	5〜16 バイト	必須	使用する "0000000000" SDK にプライマリ AID を使用させるため。
amount	BCD エンコードされた 16 進数	6 バイト	必須	BCD 形式のトランザクション金額。例：5.22 EUR は "000000000522".
currencyCode	数値 3 (ISO-4217)	3 文字	必須	トランザクション通貨。例：EUR の場合は "978" を使用してください。
countryCode	数値 3 (ISO 3166-1)	3 文字	必須	トランザクション国コード。
idd	16 進数	15 バイト	オプション	イシュア固有のデータ。

QR 支払いデータを生成する

デジタルウォレットアプリケーション内で、次を呼び出します PaymentBusinessService.generateApplicationCryptogram() 支払いタイプ PaymentType.QR を使用して、QR コードにエンコードするペイロードを生成します。

次のリスナーを実装する必要があります QRCodePaymentServiceListener.

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

実装する QRCodePaymentServiceListener

QR コードリスナーは QR コード生成中のイベントを処理します。

QR コードリスナーには 4 つのコールバックがあります：

• onAuthenticationRequired

  SDK は CDCVM 検証が必要であることを示します。参照してください CDCVM 検証を実行する.

• onDataReadyForPayment

  QR コード出力データが準備できています。

• onError

  SDK は QR コード支払い中に障害に遭遇しました。

• onNextTransactionReady

  SDK は支払いサービスの無効化を完了しました。このコールバックは QR コード生成が完了した後にのみトリガーされます。無効化ステータスを取得し、デジタル化カードの状態を確認するために使用してください。

次のコードスニペットはリスナーの基本的な実装例を示します：

QRCodePaymentServiceListener l = new QRCodePaymentServiceListener() {

    @Override
    public void onDataReadyForPayment(PaymentService paymentService,TransactionContext transactionContext) {
        // 支払いが処理され、成功しています。


        // SDK によって生成された QR コード出力データを取得します
        // MPA がペイロードを構築して QR コードシンボルを生成するために必要です
        QRCodeData qrCodeData = paymentService.getQRCodeData();

        // 画面に QR コードを表示するためのロジック
    }

    @Override
    public void onAuthenticationRequired(PaymentService activatedPaymentService, CHVerificationMethod cvm, long cvmResetTimeout)
        // SDK は CVM 検証の実行を要求します。

        if (chVerificationMethod == CHVerificationMethod.DEVICE_KEYGUARD) {
            // CVM 検証のためにデバイスのキーカードを使用するロジック
        } else if (chVerificationMethod == CHVerificationMethod.BIOMETRICS) {
            // CVM 検証のために生体認証を使用するロジック
        }

    }

    @Override
    public void onError(TransactionContext transactionContext, PaymentServiceErrorCode paymentServiceErrorCode, String s) {
        // 支払い中のエラーを処理するためのロジック。
    }

		@Override
    public void onNextTransactionReady(DeactivationStatus deactivationStatus, DigitalizedCardStatus digitalizedCardStatus, DigitalizedCard        		digitalizedCard) {
        // 支払いサービスの無効化プロセスが完了しました。
      	// 無効化ステータスを取得します
      if (deactivationStatus.getSdkStatusCode() == DEACTIVATION_SUCCESS) {
           // 無効化プロセスは正常に完了しました。次の支払いの準備ができています。
      else{
          // 無効化プロセスは失敗しました。
         	// 補充が必要か確認してください。
          if (digitalizedCardStatus.needsReplenishment())
          {
               // 補充プロセスをトリガーするロジック。
          }else{
              // デフォルトカードをリセットするロジックをトリガーする。
          }
      }
    }

QR 支払いデータを取得する

取得する QRCodeData 次のとき QRCodePaymentServiceListener.onDataReadyForPayment() がトリガーされます。

QRCodeData 次のフィールドを含みます。

フィールド	説明
statusWord	トランザクションのステータスワード。 9000 は成功を示します。参照してください ステータスワードを処理する.
cid	Cryptogram Information Data。これはこのトランザクションに CDCVM が必要かどうかを決定します。
chipDataField	暗号文を含む NFC によって計算されたチップデータフィールド。
condensedPaymentData	該当なし。
cardMainAid	支払いに使用されたメイン AID。
cardMainAppTemplate	支払いに使用されたメインアプリケーションテンプレート。
cardAliasAid	支払いに使用された代替 AID。
cardAliasAppTemplate	支払いに使用された代替アプリケーションテンプレート。
commonDataTemplate	支払い中に計算された共通データテンプレート。

ステータスワードを処理する

必ず次を確認してください statusWord 他のフィールドを使用する前に。

• 9000 はペイロード生成が成功したことを示します。その他のフィールドは QRCodeData.

• その他の値は失敗を示します。の他のフィールドを使用しないでください QRCodeData.

詳細は下の表を参照してください：

ステータスワードの値	説明
9000	トランザクションが成功しました。オブジェクト内のすべてのフィールドは、 QRCodeData 値が次の場合に利用可能です cid 0x8x 。 ここで：最初の桁は「トランザクションをオンラインで処理する要求」を示します。 2 桁目は No CVM Required、Local CDCVM entered などの CVM 情報を示します。CID が 0x8x 形式でない場合、フィールドは空になります。 CIAC 値のために顧客確認が必要であり、アプリケーションコントロールでメソッドが定義されていません。
6989	ゼロのトランザクション金額は許可されていません。
6988	トランザクション金額がイシュア定義の上限を超えています。
6987	トランザクション金額がエンドユーザー定義の上限を超えています。
6986	ATC の上限に達しているか、選択された AID が本仕様に準拠した支払いアプリケーションを参照していません。
6985	エラーを処理する

次の場合

QRCodePaymentServiceListener#onError(…) 関数が呼ばれると、エラーコードとメッセージが提供されます。 入力データが null、空、またはリスナーが のインスタンスでない場合、

、 QRCodePaymentServiceListenerIllegalArgumentException がメッセージとともにスローされます。 次の表は QR コードのエラーコードを示します：

推奨アクション

エラーコード	説明	NO_DEFAULT_CARD
デフォルトカードが設定されていません。	QR コード決済を開始する前にデフォルトカードを設定してください。	QR_CODE_PAYMENT_NOT_SUPPORTED
デフォルトカードは QR コード決済をサポートしていません。	DigitalizedCardDetails#paymentTypeSupported()	呼び出す を呼び出し、次を確認してください QR_CODE_WRONG_STATE PaymentType.QR が存在すること。
QR コード決済を開始したときに支払いサービスが既にアクティブ化されています。	エンドユーザーが CDCVM をキャンセルした場合、次を呼び出してください	PaymentBusinessService#deactivate() QR_CODE_INPUT_INVALID.
入力データは存在しますが、1 つ以上のフィールドが無効です。	有効な入力データを提供し、必要なすべてのフィールドを含めてください。SDK は JSON 構造、16 進値、値の範囲、およびフィールド長を検証します。	QR_CODE_OUTPUT_INVALID
出力データを解析できず、利用できません。	QR コード決済を失敗と見なし、QR コードを表示しないでください。	CARD_OUT_OF_PAYMENT_KEYS
支払い資格情報が利用できません。	別の支払いを試みる前に資格情報を補充してください。	QR コード画像を生成して表示する

デジタルウォレットアプリケーションは、NFC Wallet SDK が提供するデータを使用して QR コードペイロードを生成します。

QR コード支払いデータを生成した後、デジタルウォレットアプリケーションは次を行う必要があります：

SDK によって生成された暗号文の 1 つを使用してペイロードシンボルを構築する。

• Base64 でエンコードする。

• QR コードシンボルを表示する。

• ZXing ライブラリなど、QR コードをレンダリングするためのライブラリがいくつか利用可能です。

デジタルウォレットアプリケーションは、誤り訂正を微調整するために補正レベル (L、M、Q、H) を選択できます。

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