安全な支払いの確認

1. はじめに

この節およびその下位の節は非規範的である。

この仕様は、Web 上の決済フローで強力な認証方法を利用できるようにする API を定義する。これは、 [webauthn-3] と同じ認証上の利点とユーザーのプライバシーへの配慮を提供するとともに、決済処理のニーズを満たすための拡張を加えることを目指す。

[webauthn-3] と同様に、この仕様はユーザーが関与する2つの関連する処理を定義する。最初は§ 3 登録（以前は「登録手続き」と呼ばれていた）であり、ユーザーと依拠当事者との間に関係が確立される。 2つ目は§ 4 認証 - 安全な支払いの確認の支払い方法であり、ユーザーは依拠当事者からのチャレンジに応答し（場合によっては仲介する決済サービスプロバイダーを介して）、特定の支払いに同意する。

この仕様の目標は、決済手続き中の認証に伴う負担を軽減することであり、その一環として、1回の登録によってユーザーが実行できる認証の回数を最大化することが挙げられる。すなわち、依拠当事者の同意があれば、理想的にはユーザーは「一度登録するだけ」で、最初に登録した加盟店のオリジンだけでなく、あらゆる加盟店のオリジンで（決済サービスプロバイダーを介する場合も含めて）認証できるようになる。

この目的のため、安全な支払いの確認の重要な機能の1つは、加盟店（または別の主体）が依拠当事者に代わって認証手続きを開始できることである。依拠当事者は、資格情報の作成時に、この動作を許可することに明示的に同意しなければならない。

機能面では、この仕様は PaymentRequest API のための新しい支払い方法を定義し、 WebAuthn 拡張を追加して、 [webauthn-3] を支払いに固有のデータ構造とデバイスの紐付けによって拡張し、決済のコンテキストで API を呼び出せるように前提条件を緩和する。

1.1. ユースケース

[webauthn-3] は Web 向けの汎用的な認証機能を提供するが、以下のユースケースは、この仕様で定義される支払い固有の拡張の価値を示している。

オンライン取引における暗号技術に基づく認証の一般的なユースケースは、すでに十分に確立されているものとする。

1.1.1. 取引確認の暗号学的証拠

多くのオンライン決済システムでは、支払い手段を発行する主体（銀行など）が、認証によって不正行為を減らそうとすることが一般的である。 [webauthn-3] およびこの仕様により、認証器を使用して、加盟店のオリジンや取引金額、通貨などの支払い固有の重要な情報に暗号学的に署名できる。銀行は依拠当事者として、署名された支払い固有の情報を検証し、支払いを承認するかどうかの判断に利用できる。

銀行が通常の[webauthn-3] を使用する場合、検証対象となる支払い固有の情報を WebAuthn の challenge に保存しなければならない。これにはいくつかの問題がある。

これは、リプレイ攻撃を防ぐことを目的とする challenge フィールドの誤用である。
これについての仕様が存在しないため、各銀行は支払い固有の情報をチャレンジ内でどのように書式化し、符号化するかについて独自の形式を考案する必要が生じやすく、導入が複雑になり、断片化が進む。
規制によっては、支払い固有の情報がユーザーに提示され、ユーザーが同意したことを示す証拠が必要になる場合がある。通常の[webauthn-3] はこのような表示を規定していない。 challenge フィールドに保存された情報に対応する UX が仕様で定められていないためである。

これらの制約を踏まえ、安全な支払いの確認では次の動作を定めている。

challenge フィールドは、通常の [webauthn-3] と同様に、リプレイ攻撃を防ぐためだけに使用される。
SPC は支払い固有の情報の形式を規定する。これにより、汎用的な検証コードやテストスイートを開発できるようになる。
SPC は、悪意のある Web サイト（または信頼できる Web サイトに悪意を持って挿入された JavaScript コード）が回避できない方法で、ユーザーエージェントが支払い固有の情報をユーザーに提示することを保証する。
- 支払い固有の情報は、 CollectedClientData 辞書に含まれ、JavaScript によって改ざんすることはできない。
注記: 銀行や決済エコシステムのその他の関係者は、現在、 TLS、iframe、その他の Web 機能を使用したブラウザー経由の決済を十分に信頼している。この仕様は、Web 決済のセキュリティと使いやすさを向上させるように設計されている。

1.1.2. 加盟店による認証の制御

加盟店は、特に認証に伴う負担を軽減することによって、決済手続き中のユーザーの離脱を防ごうとしている。依拠当事者（銀行など）が [webauthn-3] を使用してユーザーを認証する場合、通常は iframe から行う。しかし、加盟店は依拠当事者が認証結果を検証できるようにしながら、ユーザーの認証に関する UX を自ら管理することを望んでいる。

この制約を踏まえ、安全な支払いの確認では次の動作を定めている。

SPC では、依拠当事者以外の主体も、依拠当事者に代わって認証資格情報を使用できる。その後、依拠当事者は認証結果を検証できる。

この機能には、依拠当事者が認証用のフロントエンド UX を独自に構築する必要がなくなるという利点もある。代わりに、決済サービスプロバイダーが加盟店に代わって構築することが見込まれる。

注記: 認証の UX を自ら提供したい依拠当事者は、引き続き iframe から SPC を使用して提供できる。

1.1.3. デバイスの紐付けに関する暗号学的証拠

決済業界では、デバイスを所有していることを示すシグナルが、第2の認証要素として重要な役割を果たしている。WebAuthn では、1つの資格情報を複数のデバイスで利用できる同期パスキーが認められている（Web 認証 § 1.2.1 複数デバイス資格情報を持つ消費者）。同期はログインのユースケースにおける UX を改善する一方で、一部の規制環境では、同期パスキーだけではデバイスの所有要件を満たさないという懸念が示されている。

これらの懸念から、ユーザーエージェントが作成する補助的な公開鍵と秘密鍵のペアを導入することになった。この秘密鍵は1つのデバイスにのみ存在し、そのデバイスでのみ使用される。このような鍵と SPC におけるその使用は、ブラウザーに紐付けられた鍵と呼ばれる。

1.2. API の使用シナリオ例

この節では、安全な支払いの確認に関するいくつかのシナリオと、この API を使用するための対応するサンプルコードを説明する。これらはフローの例であり、API の使用方法の範囲を制限するものではないことに注意。

1.2.1. 決済手続き中の登録

これは初回のフローであり、ユーザーがある加盟店で決済手続きを行う際に、発行銀行によって新しい資格情報が作成され、保存される。

ユーザーは merchant.example にアクセスし、購入する商品を選択して、決済手続きに進む。支払い手段の詳細を入力し、支払いを希望することを示す（例えば、「支払う」ボタンを押す）。
加盟店は、支払い手段を発行した銀行とアウトオブバンド（別のプロトコルを使用するなど）で通信する。発行銀行はユーザーの本人確認を要求し、加盟店が iframe で開くための銀行が管理する URL を提供する。
加盟店は bank.example への iframe を開き、allow 属性を次の値に設定する。「publickey-credentials-create」。
iframe 内で、発行銀行は従来の方法（SMS OTP など）によってユーザーの本人確認を行う。確認後、銀行は今後の支払いのために SPC 認証への登録をユーザーに案内する。
ユーザーが同意すると（例えば、銀行の UX にある「登録」ボタンをクリックする）、銀行は iframe 内でコードを実行する（以下の例を参照）。
ユーザーは WebAuthn の登録フローを実行する。新しい資格情報が作成され、発行銀行に返される。発行銀行はそれをユーザーおよび支払い手段に関連付けて、サーバー側のデータベースに保存する。
本人確認が完了すると、銀行の iframe が閉じられ、加盟店はユーザーの決済手続きを完了する。

この方法でユーザーを登録するためのサンプルコードを以下に示す。このサンプルコードでは、 Promise の処理を読みやすくするため、async/await が利用可能であることを前提としている。

if (!window.PublicKeyCredential) { /* クライアントは対応していない。エラーを処理する。 */ }

const publicKey = {
  // チャレンジは銀行のサーバーで作成し、iframe に送信する必要がある。
  challenge: new Uint8Array([21,31,105 /* サーバーが生成する追加の29個のランダムなバイト */]),

  // 依拠当事者:
  rp: {
    name: "Fancy Bank",
  },

  // ユーザー:
  user: {
    // WebAuthn の一部。この情報は SPC では必須ではないが、
    // 銀行のサーバーが今後の取引でこのユーザーを
    // 識別するために使用する場合がある。同じユーザーに対して
    // 一貫性のない値を使用すると、複数の資格情報が作成され、
    // 資格情報の選択によって UX に負担が生じる可能性がある。
    id: Uint8Array.from(window.atob("MIIBkzCCATigAwIBAjCCAZMwggE4oAMCAQIwggGTMII="), c=>c.charCodeAt(0)),
    name: "jane.doe@email.example",
    displayName: "Jane Doe",
  },

  // この例では、依拠当事者は ES256 または RS256 の
  // 資格情報を受け入れるが、ES256 の資格情報を優先する。
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7 // "ES256"
    },
    {
      type: "public-key",
      alg: -257 // "RS256"
    }
  ],

  authenticatorSelection: {
    userVerification: "required",
    residentKey: "required",
    authenticatorAttachment: "platform",
  },

  timeout: 360000,  // 6分間

  // これが SPC の資格情報であることを示す。現在、ブラウザーが
  // この資格情報が SPC に関連していることを認識するために必要である。
  // また、オリジン間の iframe で資格情報を作成できるようにする。
  // これはこの例で必要となる。
  //
  // 将来の仕様では、この拡張が不要になる可能性がある。
  extensions: {
    "payment": {
      isPayment: true,
      // 許可するアルゴリズムの任意のリスト。存在しないか空の場合、
      // pubKeyCredparams が使用され、デフォルトは ES256 と RS256 になる。
      // この例では ES256 と RS256 が許可され、RS256 が優先される。
      browserBoundPubKeyCredParams: [
        {
          type: "public-key",
          alg: -257 // "RS256"
        },
        {
          type: "public-key",
          alg: -7 // "ES256"
        }
      ]
    }
  }
};

// 注記: 次の呼び出しにより、認証器が UI を表示する。
try {
  const newCredentialInfo = await navigator.credentials.create({ publicKey });
  // 検証と登録のため、新しい資格情報をサーバーに送信する。
} catch(err) {
  // 使用可能な認証器がないか、ユーザーが同意を拒否した。適切に処理する。
}

1.2.2. 加盟店サイトでの認証

これは、すでに登録済みの資格情報を持つユーザーが取引を行い、発行銀行と加盟店が安全な支払いの確認を使用する場合のフローである。

ユーザーは merchant.example にアクセスし、購入する商品を選択して、決済手続きに進む。支払い手段の詳細を入力し、支払いを希望することを示す（例えば、「支払う」ボタンを押す）。
加盟店は、支払い手段の発行銀行とアウトオブバンドで通信する（別のプロトコルを使用するなど）。発行銀行はユーザーの本人確認を要求すると同時に、API の使用に必要な情報を提供することで、SPC に対応していることを加盟店に通知する。この情報には、チャレンジと、このユーザーおよび支払い手段に関連付けられた資格情報 ID が含まれる。
加盟店は以下のサンプルコードを実行する。
ユーザーは SPC の UX に表示された支払い固有の情報に同意し、続いて WebAuthn の認証手続きを実行する。署名された暗号文が加盟店に返される（AuthenticationExtensionsPaymentOutputs に含まれるブラウザーに紐付けられた鍵の出力を含む）。
加盟店は署名された暗号文を発行銀行にアウトオブバンドで送信する。発行銀行は暗号文を検証し、ユーザーが正当であること、表示された支払い固有の情報、およびユーザーが取引に同意したことを確認する。発行銀行は取引を承認し、加盟店はユーザーの決済手続きを完了する。発行銀行はブラウザーに紐付けられた鍵の公開鍵、 browserBoundPublicKeyを保存する。

ユーザーを認証するためのサンプルコードを以下に示す。このサンプルコードでは、 Promise の処理を読みやすくするため、async/await が利用可能であることを前提としている。

/* securePaymentConfirmationAvailability は、ブラウザーが */
/* SPC に対応しているかどうかを示す。このデバイスで使用可能な資格情報が */
/* ユーザーに存在するかどうかは示さない。 */
const spcAvailable =
  (await window.PaymentRequest?.securePaymentConfirmationAvailability?.()) === 'available';
if (!spcAvailable) {
  /* ブラウザーは SPC に対応していないため、加盟店は従来のフローにフォールバックする必要がある。 */
}

const request = new PaymentRequest([{
  supportedMethods: "secure-payment-confirmation",
  data: {
    // 銀行から取得した資格情報 ID のリスト。
    credentialIds,

    rpId: "fancybank.example",

    // チャレンジも銀行から取得する。
    challenge: new Uint8Array([21,31,105 /* 銀行が生成する追加の29個のランダムなバイト */]),

    instrument: {
      displayName: "FancyBank Platinum Card",
      details: "****1234 | 01/29",
      icon: "https://fancybank.example/card-art.png",
    },

    payeeName: "Merchant Shop",
    payeeOrigin: "https://merchant.example",

    paymentEntitiesLogos: [
      {
        url: "https://fancybank.example/logo.png",
        label: "Fancy Bank",
      },
      {
        url: "https://securenetwork.example/logo.png",
        label: "Secure Network",
      },
    ],

    // 検証に使用する呼び出し元の優先ロケール
    locale: ["en"],

    timeout: 360000,  // 6分間

    // 許可するアルゴリズムの任意のリスト。デフォルトは ES256 と RS256。
    // この例では ES256 と RS256 が許可され、ES256 が優先される。
    // ブラウザーに紐付けられた鍵がすでに存在する場合は新たに作成されないため、
    // このリストはブラウザーに紐付けられた鍵を新たに
    // 作成する必要がある場合にのみ使用される。
    browserBoundPubKeyCredParams: [
      {
        type: "public-key",
        alg: -7 // "ES256"
      },
      {
        type: "public-key",
        alg: -257 // "RS256"
      }
    ]
  }], {
    total: {
      label: "合計",
      amount: {
        currency: "USD",
        value: "5.00",
      },
    },
  });

try {
  const response = await request.show();
  await response.complete('success');

  // response.data は PublicKeyCredential であり、発行銀行が検証するための
  // 取引データを含む clientDataJSON を持つ。

  /* 検証のために response.data を発行銀行に送信する */
} catch (err) {
  /* SPC を使用できないため、加盟店は従来のフローにフォールバックする必要がある */
}

2. 用語

SPC 資格情報

この仕様で定義される動作に使用できるWebAuthn 資格情報。

この仕様は、依拠当事者が SPC 資格情報を他の認証フロー（例えば、ログイン）でどのように使用できるか（または使用できないか）を制限することを意図していない。

注記: この仕様の現行版では、依拠当事者が、資格情報をファーストパーティまたはサードパーティのコンテキストで使用することに明示的に同意する必要がある。長期的には、すべてのWebAuthn 資格情報がファーストパーティのコンテキスト（例えば、依拠当事者のドメイン）で SPC に使用でき、資格情報をサードパーティが使用できるようにする場合にのみ明示的な同意が必要となることを意図している。

サードパーティによる使用が有効な SPC 資格情報

SPC 資格情報のうち、依拠当事者が資格情報の作成時に、依拠当事者以外の主体による安全な支払いの確認の認証で、その資格情報を使用することに明示的に同意したもの。

SPC 資格情報がサードパーティによる使用を許可されているかどうかを非対話的に判定する手順

ユーザーエージェントが、依拠当事者識別子と資格情報 IDを与えられたときに、その ID が表す資格情報がサードパーティによる使用が有効な SPC 資格情報であるかどうかを、非対話的に（つまり、ユーザーの操作なしで）判定できる、まだ定義されていない処理。

注記: WebAuthn の課題1667を参照。

資格情報が現在のデバイスで利用可能かどうかを非対話的に判定する手順

ユーザーエージェントが、依拠当事者識別子と資格情報 IDを与えられたときに、その資格情報 ID が表す資格情報が現在のデバイスで利用可能かどうか（つまり、WebAuthn のGet 呼び出しの一部として正常に使用できるかどうか）を、非対話的に（ユーザーの操作なしで）判定できる、まだ定義されていない処理。

これにより、ユーザーエージェントは、ユーザーが取引を正常に完了できる可能性がある場合にのみ、取引確認 UXを条件付きで表示できる。

注記: この性質を実現するには、 SPC 資格情報が発見可能である必要があると考えられる。そのため、この仕様では現在、これを要件として規定している。

注記: この性質は、 WebAuthn 条件付き UI の提案で必要とされるものと非常によく似ている。両者と SPC は、同じ基盤 API でサポートできる可能性が高い。

ブラウザーに紐付けられた鍵

WebAuthn 資格情報に加えて、取引の詳細に署名する公開鍵と秘密鍵の鍵ペアであり、ユーザーエージェントによって単一のデバイスに紐付けられる。 注記: この名称は、この機能の初期の実装がブラウザー向けに作成されたことに由来するが、この概念はすべてのユーザーエージェントに適用できる。

鍵ペア

鍵ペアは、公開鍵と秘密鍵から構成される構造体であり、これらの型は実装定義である。

注記: 公開鍵と秘密鍵は、IANA COSE アルゴリズムレジストリ [IANA-COSE-ALGS-REG]で参照される暗号アルゴリズムに固有のパラメーターである。

注記: 公開鍵の部分は、登録時には CollectedClientAdditionalPaymentRegistrationData.browserBoundPublicKeyで、支払いのアサーション時には CollectedClientAdditionalPaymentData.browserBoundPublicKeyで返される。

注記: 秘密鍵は、 BrowserBoundSignature.signatureに含まれる暗号署名を生成するために使用される。ユーザーエージェントは秘密鍵をエクスポートせず、デバイスのセキュアエレメントに秘密鍵を保存する場合がある。

3. 登録

安全な支払いの確認にユーザーを登録するには、依拠当事者は navigator.credentials.create()を呼び出し、 payment WebAuthn 拡張を指定するべきである。

テスト

注記: この仕様では、条件付き UIがない場合でも、ブラウザーが SPC 資格情報 ID をキャッシュできるようにするための拡張を定義している。WebAuthn の将来のバージョンでこの機能が利用可能になれば、SPC でこの拡張を必須とする要件を削除する可能性がある。なお、SPC 資格情報（この拡張を含む）は、それ以外の点では完全な WebAuthn 資格情報である。

注記: 登録時、Web 認証では nameと displayNameの両方が必要となる。ただし、 user メンバーの定義によれば、実装はその後の認証手続きでこれらのいずれかを表示することを要求されない。2023年10月時点では、この2つのうち nameの方が一貫して表示されている。開発者は引き続き実装の動向を確認するべきである。

4. 認証 - 安全な支払いの確認の支払い方法

安全な支払いの確認によって支払いを認証するために、この仕様では次のものを定義する。

特定の支払いの認証要求を処理する支払いハンドラーである、安全な支払いの確認の支払いハンドラー。
この支払いハンドラーのための標準化された支払い方法識別子である、「secure-payment-confirmation」。

安全な支払いの確認の支払いハンドラーは、ユーザーに取引を確認させた後、認証手続きを実行してユーザーを認証し、認証手続きを表す署名済みのデータ塊を生成する。

大まかに言えば、安全な支払いの確認の認証は、 [webauthn-3]に似ているが、概念上の大きな違いが1つある。安全な支払いの確認では、サードパーティ（加盟店など）が依拠当事者に代わって認証手続きを開始し、別の未規定の経路で依拠当事者から取得した資格情報を渡すことができる。 § 1.1.2 加盟店による認証の制御を参照。

4.1. [payment-method-id]への登録

[payment-method-id]の標準化された支払い方法のレジストリに次の項目を追加する。

"secure-payment-confirmation": 安全な支払いの確認の仕様。

4.2. Payment Request コンストラクターの変更

PaymentRequest オブジェクトのコンストラクターの手順において、ステップ4.3の後に新しいステップを追加する。

支払い方法を処理する: ［サブステップ1～3は省略］
1. seenPMIs に「secure-payment-confirmation」が含まれ、 seenPMIs のサイズが1より大きい場合、 RangeErrorをスローする。

4.3. ユーザーによる有効化要件の変更

PaymentRequest.show() メソッドの手順において、ステップ2と3を次のように変更する。

requestの関連するグローバルオブジェクトが一時的な有効化を持たない場合、ユーザーエージェントは次を行ってもよい。
1. 「SecurityError」 DOMExceptionで拒否された Promiseを返す。
そうでなければ、関連するグローバルオブジェクトのユーザーによる有効化を消費する。

注記: これにより、ユーザーエージェントはユーザーによる有効化を必須としないことができる。例えば、リダイレクト時にユーザーによる有効化が存在しない可能性のあるリダイレクト認証フローをサポートできる。セキュリティ上の考慮事項については、 § 11.4 ユーザーによる有効化要件の欠如を参照。

4.4. `SecurePaymentConfirmationRequest` 辞書

dictionary SecurePaymentConfirmationRequest {
    required BufferSource challenge;
    required USVString rpId;
    required sequence<BufferSource> credentialIds;
    required PaymentCredentialInstrument instrument;
    unsigned long timeout;
    USVString payeeName;
    USVString payeeOrigin;
    sequence<PaymentEntityLogo> paymentEntitiesLogos;
    AuthenticationExtensionsClientInputs extensions;
    sequence<PublicKeyCredentialParameters> browserBoundPubKeyCredParams;
    sequence<USVString> locale;
    boolean showOptOut;
};

SecurePaymentConfirmationRequest 辞書には、次のメンバーが含まれる。

challenge

リプレイ攻撃を防ぐために依拠当事者がサーバー側で生成するランダムなチャレンジ。

rpId

資格情報の依拠当事者識別子。

credentialIds

指定された支払い手段の資格情報識別子のリスト。

instrument

登録時に表示され、取引の詳細とともに署名される支払い手段の名前とアイコンの説明。

timeout

取引の詳細への署名要求がタイムアウトするまでのミリ秒数。最大1時間。デフォルト値と許容値の範囲はユーザーエージェントによって定義される。Web 認証ではタイムアウトに関する追加の指針が提供されている。

payeeName

この SPC 呼び出しの対象となる受取人（加盟店など）の表示名。任意であり、 payeeOriginとともに、またはその代わりに指定できる。

payeeOrigin

この SPC 呼び出しの対象となる受取人（加盟店など）のオリジン。任意であり、 payeeNameとともに、またはその代わりに指定できる。

paymentEntitiesLogos

この SPC 呼び出しの対象となる支払いを仲介する主体を表すロゴの任意のリスト。表示の優先順位が高い順に並べられる。ユーザーエージェントはいずれのロゴも、またはすべてのロゴを表示する必要はない。 § 4.9 支払いが可能かどうかを確認する手順を参照。

注記: この仕様がロゴの表示方法を正確に規定していないのは意図的である。表示に関する制御をユーザーエージェントに委ね、多くの考慮事項や制約に応じて情報を最適に表示できるようにするためである。ただし、リスト内のロゴの順序は重要であり、開発者は特定の順序が望ましい結果をもたらすかどうかを実験によって判断できる。

extensions

渡された資格情報に使用する WebAuthn 拡張。呼び出し元は payment 拡張を指定する必要はない。自動的に追加されるためである。

注記: サードパーティによる SPC 呼び出しでは、この辞書が空でない場合、例外がスローされる。個人データを保存できる依拠当事者の拡張に対する攻撃を防ぐためである。 § 11.1.3 WebAuthn 拡張は依拠当事者に対してのみ許可されるを参照。

browserBoundPubKeyCredParams

ブラウザーに紐付けられた鍵に使用する暗号アルゴリズムの種類を制限する、許可された資格情報の種類のリスト。

注記: このメンバーは、ブラウザーに紐付けられた鍵を新たに作成する必要がある場合にのみ使用される。

locale

呼び出し元のロケールの優先設定を識別する言語タグ（[BCP47]を参照）の任意のリスト。これに少なくとも1つの言語タグが設定されている場合、ユーザーエージェントは、リスト内のいずれかのタグが安全な支払いの確認のダイアログで使用される言語と一致するかを判定する。指定された言語タグのいずれも一致しない場合、ユーザーエージェントは PaymentRequest.canMakePayment()が返す Promise を「NotSupportedError」 DOMExceptionで拒否する。

showOptOut

取引確認 UXの実行中に、ユーザーにオプトアウトの機会を提供するかどうか。任意であり、デフォルトは false。

4.5. 支払い方法の追加データ型

この支払い方法の支払い方法の追加データ型は SecurePaymentConfirmationRequestである。

4.6. 安全な支払いの確認が利用可能かどうかの確認

開発者が安全な支払いの確認を利用できるかどうかを簡単に確認できるように、PaymentRequestに静的 API が追加される。このメソッドである securePaymentConfirmationAvailability()は、安全な支払いの確認が利用可能であること、または利用できない場合にはその根本的な理由をある程度示す列挙型の値を返す。列挙型の出力を使用する目的は、開発者がユーザーに認証の選択肢を案内し、伝えることを支援することである。

enum SecurePaymentConfirmationAvailability {
  "available",
  "unavailable-unknown-reason",
  "unavailable-feature-not-enabled",
  "unavailable-no-permission-policy",
  "unavailable-no-user-verifying-platform-authenticator",
};

partial interface PaymentRequest {
    static Promise<SecurePaymentConfirmationAvailability> securePaymentConfirmationAvailability();
};

SecurePaymentConfirmationAvailability 列挙型には、次のメンバーが含まれる。

available

ユーザーエージェントが、呼び出し元のフレームで安全な支払いの確認 API を利用可能であると判断していることを示す。

注記: この結果は、特定の SPC 資格情報が現在または将来利用可能であるかどうかを示すものではない。

unavailable-unknown-reason

不明な理由により、呼び出し元のフレームで安全な支払いの確認 API を利用できないことを示す。ユーザーのプライバシーを保護するため、ユーザーエージェントは、より具体的な理由の代わりに常にこの結果を返してもよい。

unavailable-feature-not-enabled

機能が有効になっていないため、呼び出し元のフレームで安全な支払いの確認 API を利用できないことを示す。

unavailable-no-permission-policy

フレームに「payment」権限ポリシーがないため、呼び出し元のフレームで安全な支払いの確認 API を利用できないことを示す。

unavailable-no-user-verifying-platform-authenticator

利用可能なユーザー検証を行うプラットフォーム認証器が存在しないため、呼び出し元のフレームで安全な支払いの確認 API を利用できないことを示す。

注記: この情報は isUserVerifyingPlatformAuthenticatorAvailableを呼び出すことでも取得できるが、開発者の利便性のためにこの API にも含まれている。

特定のDocument document で securePaymentConfirmationAvailability()が呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない。ユーザーのプライバシーを保護する必要がある場合、またはユーザーエージェント固有の理由によって手順を完了できない場合、ユーザーエージェントはいつでも「unavailable-unknown-reason」を返すことを選択できる。

ユーザーエージェントが安全な支払いの確認に対応していない場合、または対応しているがユーザーエージェント固有の仕組みによって機能が無効になっている場合、「unavailable-feature-not-enabled」を返す。
document に対して「payment」権限ポリシーが有効になっていない場合、「unavailable-no-permission-policy」を返す。
利用可能なユーザー検証を行うプラットフォーム認証器が存在しない場合、「unavailable-no-user-verifying-platform-authenticator」を返す。
document で呼び出された場合に安全な支払いの確認機能が動作しないその他の理由がある場合、「unavailable-unknown-reason」を返す。
「available」を返す。

この API により、開発者は SPC フローを開始するかどうかを判断する際に、次の確認を実行できる。

const spcAvailable =
    PaymentRequest &&
    PaymentRequest.securePaymentConfirmationAvailability &&
    await PaymentRequest.securePaymentConfirmationAvailability() === 'available';

注記: SPC の機能検出には、構築済みの PaymentRequest オブジェクトで canMakePaymentを呼び出すのではなく、静的なsecurePaymentConfirmationAvailability メソッドを使用することが推奨される。

注記: この API のプライバシーに関する考慮事項については、 § 12.5 securePaymentConfirmationAvailability によるフィンガープリンティングを参照。

4.7. 安全な支払いの確認の機能の利用可能性

開発者が安全な支払いの確認の機能が利用可能かどうかを判定できるように、 PaymentRequestに静的 API が追加される。このメソッドである getSecurePaymentConfirmationCapabilities()は、機能のキーから真偽値へのレコードを返す。

partial interface PaymentRequest {
    static Promise<SecurePaymentConfirmationCapabilities> getSecurePaymentConfirmationCapabilities();
};

typedef record<DOMString, boolean> SecurePaymentConfirmationCapabilities;

SecurePaymentConfirmationCapabilitiesのキーは、辞書順の昇順で並べ替えられなければならない。キーの集合には、 SecurePaymentConfirmationCapabilityの列挙値の集合を含めるべきである。ただし、ユーザーエージェントは必要と判断した場合、キーを省略してもよい。 § 12.6 getSecurePaymentConfirmationCapabilities によるフィンガープリンティングを参照。

特定の機能の値が true の場合、その機能はこのユーザーエージェントの安全な支払いの確認の実装で現在サポートされていることが確認されている。

特定の機能の値が false の場合、その機能はこのユーザーエージェントの安全な支払いの確認の実装で現在サポートされていないことが確認されている。

機能がキーとして存在しない場合、その機能がこのユーザーエージェントの安全な支払いの確認の実装でサポートされているかどうかは不明である。

この API により、開発者は安全な支払いの確認のフローを開始するかどうかを判断する際に、次のように特定の機能のサポート状況を確認できる。

if (PaymentRequest && PaymentRequest.getSecurePaymentConfirmationCapabilities) {
    const capabilities = await PaymentRequest.getSecurePaymentConfirmationCapabilities();
    if (capabilities.browserBoundKeyHardware) {
        // SPC API を使用する際、ハードウェアによって保護された BBK が利用可能になる。
    }
}

注記: この API のプライバシーに関する考慮事項については、 § 12.6 getSecurePaymentConfirmationCapabilities によるフィンガープリンティングを参照。

4.7.1. `SecurePaymentConfirmationCapability` 列挙型

enum SecurePaymentConfirmationCapability {
  "browserBoundKeyHardware",
};

この列挙型は、安全な支払いの確認の機能のうち、開発者が評価してユーザーに特定のワークフローや体験を提供するために利用できる限定的な集合を定義する。

browserBoundKeyHardware

安全な支払いの確認 API が、デバイス上のハードウェアセキュアエレメントに保存されたブラウザーに紐付けられた鍵を使用できることを示す。

詳細については、§ 6 ブラウザーに紐付けられた鍵のストアを参照。

4.8. 支払い方法データを検証する手順

入力としてPaymentRequest request と SecurePaymentConfirmationRequest data を受け取る、この支払い方法の支払い方法データを検証する手順は次のとおりである。

テスト

data["credentialIds"]が空の場合、 RangeErrorをスローする。
data["credentialIds"]内の各 id について、次を行う。
1. id が空の場合、 RangeErrorをスローする。
data["challenge"]が null または空の場合、TypeErrorをスローする。
data["instrument"]["displayName"]が空の場合、TypeErrorをスローする。
data["instrument"]["icon"]が空の場合、TypeErrorをスローする。
data["instrument"] ["icon"]に対して URL パーサーを実行する。これが失敗を返した場合、 TypeErrorをスローする。
data["instrument"]["details"]が存在するが空の場合、TypeErrorをスローする。
data["rpId"]が有効なドメインでない場合、 TypeErrorをスローする。
data["payeeName"]と data["payeeOrigin"]の両方が省略されている場合、 TypeErrorをスローする。
data["payeeName"]または data["payeeOrigin"]のいずれかが存在し、かつ空の場合、TypeErrorをスローする。
data["payeeOrigin"]が存在する場合:
1. data["payeeOrigin"]に対して URL パーサーを実行した結果を parsedURL とする。
2. parsedURL が失敗の場合、 TypeErrorをスローする。
3. parsedURL のスキームが「https」でない場合、 TypeErrorをスローする。
data["paymentEntitiesLogos"]が存在し、空でない場合:
1. data["paymentEntitiesLogos"]内の各 logo について:
  1. logo["url"]が空の場合、 TypeErrorをスローする。
  2. logo["url"]に対して URL パーサーを実行する。これが失敗を返した場合、TypeErrorをスローする。
  3. logo["label"]が空の場合、 TypeErrorをスローする。
data["extensions"]が存在し、空でなく、かつ data["rpId"]が request の関連する設定群オブジェクトのオリジンでない場合、 TypeErrorをスローする。
data["locale"]が存在し、かつ空でない場合:
1. 安全な支払いの確認のダイアログで使用される言語タグを dialogLanguageTag とする。
2. matched を false とする。
3. data["locale"]内の各 tag について:
  1. tag が整形式の [BCP47] 言語タグでない場合、 TypeErrorをスローする。
  2. tag と dialogLanguageTag の両方に複数の言語サブタグが含まれ、 tag と dialogLanguageTag が ASCII 大文字小文字を区別せず一致する場合、 matched を true に設定し、ループを抜ける。
  3. tag または dialogLanguageTag の少なくとも一方が第一言語サブタグのみで構成され（[BCP47]を参照）、両者の第一言語サブタグがASCII 大文字小文字を区別せず一致する場合、 matched を true に設定し、ループを抜ける。
4. matched が false の場合、「NotSupportedError」 DOMExceptionをスローする。
注記: 一致が見つからない場合に NotSupportedErrorを返すことで、ダイアログのロケールが要求されたどのロケール設定とも一致しないことを呼び出し元に通知できる。

注記: ここでは標準的な言語ネゴシエーションは適用されない。その結果得られる言語やロケールが、安全な支払いの確認のダイアログには使用されないためである。

注記: localeは、特定の入力メンバーに関連付けられた言語や方向のメタデータとは異なる。これは特定の文字列値に関する表明ではなく、呼び出し元が要求するローカライズされた体験を表すためである。詳細については、 § 14 国際化に関する考慮事項を参照。

4.9. 支払いが可能かどうかを確認する手順

この支払い方法の支払いが可能かどうかを確認する手順は、入力として SecurePaymentConfirmationRequest data を受け取り、次のとおりである。

テスト

data["payeeOrigin"]が存在する場合:
1. data["payeeOrigin"]に対して URL パーサーを実行した結果を parsedURL とする。
2. 表明: parsedURL は失敗ではない。
3. 表明: parsedURL のスキームは「https」である。
注記: これらの事前条件は、すでに支払い方法データを検証する手順で確認されている。
1. data["payeeOrigin"]を parsedURL のオリジンの直列化結果に設定する。
アイコンの画像リソースを取得する。その際、 «["src" → data["instrument"]["icon"]]» を image に渡す。これが失敗した場合:
1. data["instrument"]["iconMustBeShown"]が true の場合、false を返す。
2. そうでなければ、data["instrument"]["icon"]を空文字列に設定する。
  
  注記: これにより、RP は指定されたアイコンが表示されなかったことを認識できる。出力されるinstrumentのアイコン文字列が空になるためである。
注記: 資格情報が一致するかどうかにかかわらず、画像リソースを取得しなければならない。これは資格情報の存在を探る試みを防ぐためである。
任意で、ユーザーエージェントは data["paymentEntitiesLogos"]から項目を削除してもよい。その場合、リストの末尾から先頭に向かって削除する。

注記: これにより、ユーザーエージェントは表示するロゴの数を制御できる。同時に、呼び出し元にとってロゴが表示優先度の降順に並ぶという意味が維持される。
data["paymentEntitiesLogos"]内の各 logo について:
1. logo の画像リソースを取得する。その際、 «["src" → logo["url"]]» を image に渡し、結果を復号する。
2. 取得または復号のいずれかが失敗した場合、logo["url"]を空文字列に設定する。
  
  注記: これにより、RP は指定されたロゴが表示されなかったことを認識できる。出力されるpaymentEntitiesLogos シーケンス内で、そのロゴの URL 文字列が空になるためである。
注記: 資格情報が一致するかどうかにかかわらず、ロゴのリソースを取得しなければならない。これは資格情報の存在を探る試みを防ぐためである。
data["credentialIds"]内の各 id について:
1. data["rpId"]と id を渡して、資格情報が現在のデバイスで利用可能かどうかを非対話的に判定する手順を実行する。結果が false の場合、 data["credentialIds"]から id を削除する。
2. data["rpId"]が request の関連する設定群オブジェクトのオリジンでない場合、 data["rpId"]と id を渡して、 SPC 資格情報がサードパーティによる使用を許可されているかどうかを非対話的に判定する手順を実行する。結果が false の場合、 data["credentialIds"]から id を削除する。
true を返す。

4.10. 取引確認 UX の表示

PaymentRequest.show()が呼び出され、安全な支払いの確認の支払いハンドラーが選択された場合（そのアルゴリズムのステップ19～24）、ユーザーエージェントは、ユーザーが処理を続行するかどうか、およびどのように続行するかを選択できるユーザーインターフェイスを提示しなければならない。

4.10.1. ユーザーに提示される情報

ユーザーエージェントの実装上の選択を制限しないため、この仕様では特定のユーザーインターフェイスの表示を要求しない。ただし、依拠当事者が CollectedClientPaymentDataに含まれる情報を信頼できるように、ユーザーエージェントは、以下の情報がユーザーに伝えられ、認証に対するユーザーの同意が得られることを保証しなければならない。

payeeNameが存在する場合は、その値。
payeeOriginが存在する場合は、その値。
total、すなわち取引の currencyと value。
instrumentの詳細、すなわち支払い手段の displayName、 details、および icon。入力のiconから画像リソースを取得または復号できなかった場合、ユーザーエージェントはアイコンを表示しないか、代わりに汎用的な支払い手段のアイコンを表示してもよい。

注記: 指定されたアイコンを取得または復号できなかった場合、 iconMustBeShownはここでは false でなければならない。そうでなければ、支払いが可能かどうかを確認する手順がすでに失敗しているはずだからである。
paymentEntitiesLogosの url項目によって表されるロゴ。空でない場合に限る。
- ユーザーエージェントは、各 PaymentEntityLogoの labelを表示する必要はないが、アクセシビリティのために使用するべきである。 labelは引き続きCollectedClientAdditionalPaymentDataに含まれ、署名の対象となる。

showOptOutが true の場合、ユーザーエージェントはユーザーが指定された依拠当事者の処理からオプトアウトしたいことを示す機会を提供しなければならない。

テスト

authentication-optout.https.html （ライブテスト）（ソース）

4.10.2. 取引確認 UX の結果

ユーザーエージェントは、処理を続行するかどうか、およびどのように続行するかについて、次のいずれかをユーザーが示せるようにしなければならない。

ユーザーがSPC 資格情報を使用して認証し、支払いを続行することを希望する場合、

ユーザーが操作している PaymentRequestに対して、ユーザーが支払い要求を受け入れるアルゴリズムを実行する。

ユーザーは支払いの続行を希望するが、 data["credentialIds"]が空であるため使用できないか、またはSPC 資格情報の使用を希望しない場合、

次の手順を実行する。

data["credentialIds"]を空のリストに設定する。

注記: これにより、 PaymentRequest.show()の Promise が「NotAllowedError」 DOMExceptionで拒否される。 § 4.11 支払い要求に応答する手順を参照。
ユーザーが操作している PaymentRequestに対して、ユーザーが支払い要求を受け入れるアルゴリズムを実行する。

テスト

authentication-auth-another-way.https.html （ライブテスト）（ソース）

ユーザーが支払いの続行を希望しない場合、

ユーザーが操作している PaymentRequestに対して、ユーザーが支払い要求を中止するアルゴリズムを実行する。

注記: これにより、 PaymentRequest.show()の Promise は「AbortError」 DOMExceptionで拒否される。

ユーザーが 指定された依拠当事者の処理からオプトアウトすることを希望する場合、

PaymentRequest.show()を「OptOutError」 DOMExceptionで拒否する。 § 12.7 ユーザーによるオプトアウトを参照。

注記: この選択肢をユーザーに提供する必要があるのは、 showOptOutが true に設定されている場合のみである。

4.10.3. テスト自動化のサポート

現在の取引自動化モードが「none」でない場合、ユーザーエージェントはまず自動化コンテキスト内にあることを確認するべきである（ WebDriver のセキュリティに関する考慮事項を参照）。その後、ユーザーエージェントは、前述の情報の伝達とユーザーの同意の取得を省略し、代わりに現在の取引自動化モードの値に基づいて次の処理を行うべきである。

"autoAccept": ユーザーが取引の詳細を確認し、承諾したものとして動作する。
"autoChooseToAuthAnotherWay": ユーザーが取引の詳細を確認して承諾したものの、認証にSPC 資格情報を使用したくないことも示したものとして動作する。 data["credentialIds"]が空の場合、これは「autoAccept」と同等である。
"autoReject": ユーザーが取引の詳細を確認して拒否した（つまり、取引を続行したくない）ものとして動作する。
"autoOptOut": ユーザーが取引の詳細を確認し、オプトアウトしたいことを示したものとして動作する。

4.11. 支払い要求に応答する手順

この支払い方法の支払い要求に応答する手順は、指定された PaymentRequest request と SecurePaymentConfirmationRequest data に対して、次のとおりである。

注記: これらの手順は、ユーザーが取引確認 UXを受け入れた場合にのみ実行される。ユーザーが支払い要求を受け入れるアルゴリズムによって呼び出される。

data["credentialIds"]が空の場合、「NotAllowedError」 DOMExceptionをスローする。これにより、ユーザーが SPC を認証に使用できない場合、または使用したくない場合の認証手続きのプライバシーが維持される。

注記: ここで例外をスローすると、 PaymentRequest.show()の Promise は「NotAllowedError」 DOMExceptionで拒否される。
request の関連する設定群オブジェクトのトップレベルオリジンを topOrigin とする。
payment を新しい AuthenticationExtensionsPaymentInputs 辞書とし、そのフィールドは次のとおりとする。

isPayment

真偽値 true。

rpId

data["rpId"]

topOrigin

topOrigin

payeeName

data["payeeName"]。存在する場合に限り、そうでなければ省略する。

payeeOrigin

data["payeeOrigin"]。存在する場合に限り、そうでなければ省略する。

paymentEntitiesLogos

data["paymentEntitiesLogos"]。存在し、空でない場合に限り、そうでなければ省略する。

この仕様の現行版では、各 PaymentEntityLogoにつき1つの URL のみをサポートしている。したがって、単にデータ構造をコピーして署名するだけで、ユーザーに表示された内容を示すのに十分である。将来の仕様では、例えばダークモードをネイティブにサポートするために、各PaymentEntityLogoに複数の URL を追加する可能性がある。その場合、仕様では、指定された PaymentEntityLogoについて、どの URL が表示されたかを依拠当事者に示す必要がある。

total

request.[[details]]["total"]

instrument

data["instrument"]

browserBoundPubKeyCredParams

data["browserBoundPubKeyCredParams"]
extensions を新しい AuthenticationExtensionsClientInputs 辞書とし、そのpayment メンバーを payment に設定し、その他のメンバーを data["extensions"]から設定する。
publicKeyOpts を新しい PublicKeyCredentialRequestOptions 辞書とし、そのフィールドは次のとおりとする。

challenge

data["challenge"]

timeout

data["timeout"]

rpId

data["rpId"]

userVerification

required

extensions

extensions

注記: このアルゴリズムでは、 userVerificationの値を「required」に固定している。これは Chrome の初期実装がサポートする値だからである。現在の制約は将来変更される可能性がある。ワーキンググループは、他の値（「preferred」や「discouraged」など）のサポートが有益となるユースケースを実装者が共有することを歓迎する。
data["credentialIds"]内の各 id について:
1. descriptor を新しい PublicKeyCredentialDescriptor 辞書とし、そのフィールドは次のとおりとする。
  
  type
  
  public-key
  
  id
  
  id
  
  transports
  
  唯一のメンバーが internalである、長さ1のシーケンス。
2. descriptor を publicKeyOpts["allowCredentials"]に付加する。
«["publicKey" → publicKeyOpts]»を渡して、資格情報を要求するアルゴリズムを実行した結果を outputCredential とする。

注記: Chrome の初期実装では、 data.credentialIds のリスト全体を資格情報を要求する処理に渡さない。代わりに、リスト内から現在のデバイスに一致する資格情報を1つ選択し、それだけを渡す。

注記: これにより、 [webauthn-3]の Get 動作が開始される。
outputCredential を返す。

5. WebAuthn 拡張 - 「`payment`」

このクライアントの登録拡張および認証拡張は、それぞれ資格情報が安全な支払いの確認のために作成されるか、使用されるかを示す。

登録時、この拡張により、ブラウザーは安全な支払いの確認の資格情報 ID を識別してキャッシュできる。認証時には、この拡張によってサードパーティが依拠当事者に代わって認証手続きを実行できるようになり、署名された暗号文に取引情報も追加される。

特に、Web サイトはこの拡張を指定して navigator.credentials.get()を直接呼び出すべきではない。認証時、この拡張には「secure-payment-confirmation」支払い方法を指定した PaymentRequestからのみアクセスできる。

注記: 以前は、payment 拡張によってオリジン間の iframe 内で資格情報を作成できた。しかし、WebAuthn PR #1801以降、この動作は WebAuthn でデフォルトで許可されている。

テスト

このテストは仕様の特定の行に直接対応するものではなく、オリジン間の iframe 内から認証を開始できることをテストするものである。この動作は、それを禁止する規定が存在しないことによって定められている。

authentication-in-iframe.sub.https.html （ライブテスト）（ソース）

拡張識別子

payment

適用可能な操作

登録および認証

クライアント拡張の入力

partial dictionary AuthenticationExtensionsClientInputs {
  AuthenticationExtensionsPaymentInputs payment;
};

dictionary AuthenticationExtensionsPaymentInputs {
  boolean isPayment;
  sequence<PublicKeyCredentialParameters> browserBoundPubKeyCredParams;

  // 認証時にのみ使用される。
  USVString rpId;
  USVString topOrigin;
  USVString payeeName;
  USVString payeeOrigin;
  sequence<PaymentEntityLogo> paymentEntitiesLogos;
  PaymentCurrencyAmount total;
  PaymentCredentialInstrument instrument;
};

isPayment

拡張が有効であることを示す。

rpId