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 を提供するために 金額, 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 を使用できるようにします。
金額	BCD エンコードされた 16 進数	6 バイト	必須	BCD 形式の取引金額。例: 5.22 EUR は "000000000522".
currencyCode	数値 3（ISO-4217）	3 文字	必須	取引通貨。例: 次を使用します "978" EUR には
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 検証に Device Keyguard を使用するロジック
        } else if (chVerificationMethod == CHVerificationMethod.BIOMETRICS) {
            // CVM 検証に Biometrics を使用するロジック
        }

    }

    @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	暗号データ情報。このトランザクションで CDCVM が必要かどうかを決定します。
chipDataField	NFC によって計算されたチップデータフィールド。暗号文を含みます。
condensedPaymentData	該当なし。
cardMainAid	支払いに使用されるメイン AID。
cardMainAppTemplate	支払いに使用されるメインアプリケーションテンプレート。
cardAliasAid	支払いに使用される代替 AID。
cardAliasAppTemplate	支払いに使用される代替アプリケーションテンプレート。
commonDataTemplate	支払い中に計算される共通データテンプレート。

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

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

• 9000 ペイロード生成の成功を示します。次の他のフィールドを読み取ることができます QRCodeData.
• その他の値は失敗を示します。次の他のフィールドは使用しないでください QRCodeData.

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

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

エラーを処理する

次の場合、 QRCodePaymentServiceListener#onError(… ) 関数が呼び出されると、エラーコードとメッセージが提供されます。

入力データが null または空である場合、あるいはリスナーが次のインスタンスではない場合 QRCodePaymentServiceListener、 IllegalArgumentException メッセージ付きでスローされます。

次の表に QR コードのエラーコードを示します:

エラーコード	説明	推奨アクション
NO_DEFAULT_CARD	デフォルトカードが設定されていません。	QR コード決済を開始する前に、デフォルトカードを設定してください。
QR_CODE_PAYMENT_NOT_SUPPORTED	デフォルトカードは QR コード決済をサポートしていません。	呼び出します DigitalizedCardDetails#paymentTypeSupported() および確認 PaymentType.QR が存在します。
QR_CODE_WRONG_STATE	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）を選択して、エラー訂正を細かく調整できます。