QRコード決済を実装する

概要

NFC Wallet SDK は Thales のホワイトラベル EMV PURE カードに対してのみ QR コード支払いをサポートします。

QR コード支払いを実装する前に、次を完了してください トークン化。参照してください カードをトークン化する.

SDK 統合

前提条件を確認する

デジタルカードが QR コード支払いをサポートしていることを次で確認します DigitalCard.Details.isPaymentTypeSupported() 次のパラメータで PaymentType.qr.

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

QR 決済の入力データを作成します

作成 QRPaymentSession.QRPaymentInputData。これは QR コード決済ペイロードを構築するために使用される取引パラメータを含みます。

let amount   = "000000500030"  // 5000.30 EUR
let currency = "0978" // EUR
let aid      = "00000000000000000000000000000000"    // 16 バイト
let idd      = "000000000000000000000000000000"      // 15 バイト
let inputData = QRPaymentSession.QRPaymentInputData(amount: amount, currencyCode: currency, aid: aid, idd: idd)

QRPaymentSession.QRPaymentInputData は次のフィールドを持ちます：

入力データ	形式	長さ	説明
aid	16 進数 ISO/IEC 7816-5	10〜32 文字	必須 SDK にプライマリ AID を使用させるには "0000000000" を使用してください。
amount	BCD エンコードされた 16 進数	12 文字	必須 BCD 形式の取引金額。 5.22 EUR の金額は「000000000522」という値になります。
currencyCode	ISO-4217 数値文字列	4 文字	必須 取引通貨。 EUR の場合は "0978" を使用してください。
idd	16 進数	30 文字	任意 イシュア固有のデータ

QR 決済データを生成する

デジタルウォレットアプリ内で、次を呼び出します generateQRPaymentData を呼び出して、QR コードにエンコードするペイロードを生成します。

この API はエラーをスローする可能性があります。参照： エラーを処理する.

成功すると、API は次を返します QRPaymentOutputData 次のフィールドを持ちます：

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

非デフォルトのデジタルカードを使用して QR コード支払いを行うには、次を渡します digitalCardID に generateQRPaymentData.

ステータスワードの扱い

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

• 9000 はペイロード生成の成功を示します。 他のフィールドはで読み取ることができます QRPaymentOutputData.

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

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

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

エラーを処理する

もし generateQRPaymentData がエラーをスローした場合、支払いは失敗とみなしてください。UI 状態をリセットし、エンドユーザーに次に取るべき最良の行動を案内してください。

エラー	説明
deviceEnvironmentUnsafe	デバイスがセキュリティ要件を満たしていません。
sessionInProgress	別の決済セッションがまだ実行中です。
unsupportedPaymentType	デジタルカードは QR コード支払いをサポートしていません。
invalidQRInputData	の一つ以上のフィールドが欠落しているか形式が不正です。 QRPaymentInputData は欠落しているか形式が不正です。
qrPaymentFailed	内部障害によりペイロードを生成できませんでした。
authenticationKeyInvalidated	デバイスのパスコードが無効化され、セキュアストレージが消去されました。
biometricNotEnrolled	生体認証が利用できないか登録されていません。

各エラーには失敗を説明するメッセージが含まれる場合があります。トラブルシューティングやサポート診断にそれを使用してください。

NFC Wallet SDK は、発生したときに保存された認証情報を自動的に消去します authenticationKeyInvalidated （例：パスコードのリセットやセキュリティ変更後）。

あなたのアプリケーションはエンドユーザーに再登録の手順を案内するべきです。

完全な実装例

このコードサンプルを使用して、前の手順がどのように結びつくかを理解してください。

func generateOutputData(digitalCard: DigitalCard?) async -> QRPaymentSession.QRPaymentOutputData? {
    do {
        let paymentSession = QRPaymentSession()
        // 該当する場合、QR コード支払いの最大金額を使用してください。
        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 コード支払い
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, userPrompt: "Authenticate")
        } else {
            // 指定されたデジタルカードでの QR コード支払い
            return try await paymentSession.generateQRPaymentData(withQRPaymentInputData: inputData, digitalCardID: digitalCard?.digitalCardID, userPrompt: "Authenticate")
        }
        
    } catch {
        // エラーを処理する
        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
    }
}

QR コード画像を生成して表示する

デジタルウォレットアプリケーションは、NFC Wallet SDK が返す出力を使用して QR コード画像を生成および表示する責任があります。

を受け取った後、 QRPaymentOutputData QR コード支払いのために、デジタルウォレットアプリケーションは次を実行する必要があります：

1. QR コードペイロードを構築する。

2. QR コード画像を生成する。

3. POS で提示するためにエンドユーザーに QR コード画像を表示する。

iOS はネイティブに QR コード生成をサポートします（Core Image）。