支払いハンドラ API

支払いハンドラが商人がshow() メソッドを呼び出したときに登録されていない場合、ユーザーエージェントはトランザクション中にユーザーがこの支払いハンドラを登録することを許可する可能性があります（「ジャストインタイム」）。

このセクションの残りの内容は規範ではありません。

ユーザーエージェントは、商人が要求したURLベースの支払い方法識別子を通じて見つかったpayment method manifestから支払いハンドラ情報を導出することにより、ジャストインタイムインストールを実行する場合があります。

WebIDLpartial interface ServiceWorkerRegistration {
  [SameObject] readonly attribute PaymentManager paymentManager;
};

paymentManager 属性は支払いハンドラ管理機能を公開します。

WebIDL[SecureContext, Exposed=(Window)]
interface PaymentManager {
  attribute DOMString userHint;
  Promise<undefined> enableDelegations(sequence<PaymentDelegation> delegations);
};

PaymentManager は支払いハンドラが自身のサポートする委任（delegations）を管理するために使用されます。

WebIDLenum PaymentDelegation {
  "shippingAddress",
  "payerName",
  "payerPhone",
  "payerEmail"
};

"shippingAddress"

支払いハンドラは必要に応じて配送先住所を提供します。

"payerName"

支払いハンドラは必要に応じて支払人の名前を提供します。

"payerPhone"

支払いハンドラは必要に応じて支払人の電話番号を提供します。

"payerEmail"

支払いハンドラは必要に応じて支払人のメールアドレスを提供します。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

CanMakePaymentEvent は、支払いハンドラが支払い要求に応答できるかどうかのシグナルとして用いられる。

WebIDL[Exposed=ServiceWorker]
interface CanMakePaymentEvent : ExtendableEvent {
  constructor(DOMString type);
  undefined respondWith(Promise<boolean> canMakePaymentResponse);
};

PaymentRequest を受信したら、ユーザーエージェントは次の手順をMUST実行する:

1. ユーザーエージェントの設定が CanMakePaymentEvent の使用を禁止している（例：プライベートブラウジングモードの場合）なら、これらの手順を終了する。
2. registration を、ServiceWorkerRegistration とする。
3. registration が見つからない場合、これらの手順を終了する。

4. 機能イベントを発火 "canmakepayment" を、registration 上で CanMakePaymentEvent を用いて行う。

PaymentMethodData と、支払い方法識別子で一致する支払いハンドラが与えられたとき、このアルゴリズムはその支払いハンドラが支払いに使用できる場合に true を返す:

1. methodName を、PaymentMethodData に指定された支払い方法識別子の文字列とする。
2. methodData を、PaymentMethodData の支払い方法固有データとする。
3. paymentHandlerOrigin を、支払いハンドラの ServiceWorkerRegistration のスコープ URL のorigin とする。
4. paymentMethodManifest を、methodName の取り込みおよび解析済みの支払い方法マニフェストとする。
5. もし methodName が、paymentMethodManifest の "*" 文字列のサポートされるオリジンを持つURL ベースの支払い方法識別子であるなら、true を返す。
6. それ以外で、URL ベースの支払い方法識別子である methodName のorigin が paymentHandlerOrigin と同じである場合、支払いハンドラで CanMakePaymentEvent を発火し、その結果を返す。
7. それ以外で、paymentMethodManifest のサポートされるオリジンが paymentHandlerOrigin を含むorigin の順序付き集合である場合、支払いハンドラで CanMakePaymentEvent を発火し、その結果を返す。
8. それ以外の場合、false を返す。

本仕様は ServiceWorkerGlobalScope インターフェイスを拡張する。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

PaymentRequestDetailsUpdate は、更新された合計（必要に応じて修飾子や配送オプションを含む）および、支払い方法・配送先住所・配送オプションのユーザー選択に起因する可能性のあるエラーを含む。

WebIDLdictionary PaymentRequestDetailsUpdate {
  DOMString error;
  PaymentCurrencyAmount total;
  sequence<PaymentDetailsModifier> modifiers;
  sequence<PaymentShippingOption> shippingOptions;
  object paymentMethodErrors;
  AddressErrors shippingAddressErrors;
};

PaymentRequestEvent は、ユーザーによる選択後に Payment Handler で利用可能なデータとメソッドを表す。ユーザーエージェントは、PaymentRequest で利用可能なデータのサブセットを Payment Handler に伝える。

WebIDL[Exposed=ServiceWorker]
interface PaymentRequestEvent : ExtendableEvent {
  constructor(DOMString type, optional PaymentRequestEventInit eventInitDict = {});
  readonly attribute USVString topOrigin;
  readonly attribute USVString paymentRequestOrigin;
  readonly attribute DOMString paymentRequestId;
  readonly attribute FrozenArray<PaymentMethodData> methodData;
  readonly attribute object total;
  readonly attribute FrozenArray<PaymentDetailsModifier> modifiers;
  readonly attribute object? paymentOptions;
  readonly attribute FrozenArray<PaymentShippingOption>? shippingOptions;
  Promise<WindowClient?> openWindow(USVString url);
  Promise<PaymentRequestDetailsUpdate?> changePaymentMethod(DOMString methodName, optional object? methodDetails = null);
  Promise<PaymentRequestDetailsUpdate?> changeShippingAddress(optional AddressInit shippingAddress = {});
  Promise<PaymentRequestDetailsUpdate?> changeShippingOption(DOMString shippingOption);
  undefined respondWith(Promise<PaymentHandlerResponse> handlerResponsePromise);
};

WebIDLdictionary PaymentRequestEventInit : ExtendableEventInit {
  USVString topOrigin;
  USVString paymentRequestOrigin;
  DOMString paymentRequestId;
  sequence<PaymentMethodData> methodData;
  PaymentCurrencyAmount total;
  sequence<PaymentDetailsModifier> modifiers;
  PaymentOptions paymentOptions;
  sequence<PaymentShippingOption> shippingOptions;
};

PaymentRequestEvent のインスタンスは、次の表の内部スロットを持って作成される:

PaymentRequest を PaymentRequest.show() によって受け取り、その後ユーザーが支払いハンドラを選択した場合、ユーザーエージェントは次の手順を MUST 実行する:

1. registration を、ユーザーが選択した支払いハンドラに対応する ServiceWorkerRegistration とする。
2. registration が見つからない場合、Promise を、PaymentRequest.show() によって作成されたものに対して "InvalidStateError" の DOMException で拒否し、これらの手順を終了する。

3. 機能イベントを発火 "paymentrequest" を、registration 上で PaymentRequestEvent を用いて、次のプロパティとともに行う:

   topOrigin

   最上位の支払い先ウェブページのオリジンの直列化。

   paymentRequestOrigin

   PaymentRequest が初期化されたコンテキストのオリジンの直列化。

   methodData

   MethodData の生成アルゴリズム を実行した結果。

   modifiers

   Modifiers の生成アルゴリズム を実行した結果。

   total

   対応する PaymentRequest の PaymentDetailsInit 上の total フィールドのコピー。

   paymentRequestId

   PaymentRequest の \[\[details\]\].id。

   paymentOptions

   対応する PaymentRequest のコンストラクターに渡された paymentOptions 辞書のコピー。

   shippingOptions

   対応する PaymentRequest の PaymentDetailsInit 上の shippingOptions フィールドのコピー。

   その後、dispatchedEvent について並行して次の手順を実行する:

   1. dispatchedEvent の寿命延長プロミスに含まれるすべてのプロミスが解決するのを待つ。
   2. もし 支払いハンドラが PaymentHandlerResponse を提供していない場合、Promise（PaymentRequest.show() によって作成されたもの）を "OperationError" の DOMException で拒否する。

1. event を、この PaymentRequestEvent とする。
2. event の isTrusted 属性が false の場合、"InvalidStateError" の DOMException で拒否された Promise を返す。
3. request を、この PaymentRequestEvent をトリガーした PaymentRequest とする。
4. url を、url 引数を parsing した結果とする。
5. URL のパースで例外がスローされた場合、その例外で拒否された Promise を返す。
6. url が about:blank の場合、TypeError で拒否された Promise を返す。
7. url の origin が、支払いハンドラに関連付けられた service worker の origin と同一でない場合、null で解決された Promise を返す。
8. promise を新しい Promise とする。
9. promise を返し、残りの手順を並行して実行する:
10. event.[[windowClient]] が null でない場合:
    1. event.[[windowClient]].visibilityState が "unloaded" でないなら、promise を "InvalidStateError" の DOMException で拒否し、これらの手順を中止する。
11. newContext を新しい top-level browsing context とする。
12. Navigate を用いて、例外有効・置換有効で newContext を url に移動する。
13. ナビゲーションで例外がスローされた場合、その例外で promise を拒否し、これらの手順を中止する。
14. newContext の origin が、支払いハンドラに関連付けられた service worker client の origin と同一でない場合:
    1. promise を null で解決する。
    2. これらの手順を中止する。
15. client を、create window client アルゴリズムを newContext を引数として実行した結果とする。
16. event.[[windowClient]] に client を設定する。
17. promise を client で解決する。

WebIDLdictionary PaymentHandlerResponse {
DOMString methodName;
object details;
DOMString? payerName;
DOMString? payerEmail;
DOMString? payerPhone;
AddressInit shippingAddress;
DOMString? shippingOption;
};

このアルゴリズムが methodName および methodDetails のパラメータで呼び出されたとき、ユーザーエージェントは次の手順を MUST 実行する:

1. payment method changed algorithm を、与えられた methodName および methodDetails パラメータを用いて構築した PaymentMethodChangeEvent event で実行する。
2. event.updateWith(detailsPromise) が実行されなかった場合、null を返す。
3. event.updateWith(detailsPromise) が例外を投げた場合、そのエラーを再スローする。
4. event.updateWith(detailsPromise) がタイムアウトした場合（任意）、"InvalidStateError" の DOMException を投げる。
5. event.updateWith(detailsPromise) の detailsPromise から、PaymentRequestDetailsUpdate を構築して返す。

このアルゴリズムが shippingAddress または shippingOption で呼び出されたとき、ユーザーエージェントは次の手順を MUST 実行する:

1. PaymentRequest updated algorithm を、更新された詳細（shippingAddress または shippingOption）を用いて構築した PaymentRequestUpdateEvent event で実行する。
2. event.updateWith(detailsPromise) が実行されなかった場合、null を返す。
3. event.updateWith(detailsPromise) が例外を投げた場合、そのエラーを再スローする。
4. event.updateWith(detailsPromise) がタイムアウトした場合（任意）、"InvalidStateError" の DOMException を投げる。
5. event.updateWith(detailsPromise) の detailsPromise から、PaymentRequestDetailsUpdate を構築して返す。

このアルゴリズムが event および handlerResponsePromise のパラメータで呼び出されたとき、ユーザーエージェントは次の手順を MUST 実行する:

1. event の isTrusted が false の場合、"InvalidStateError" の DOMException を投げ、これらの手順を中止する。
2. event の dispatch flag が未設定の場合、"InvalidStateError" の DOMException を投げ、これらの手順を中止する。
3. event.[[respondWithCalled]] が true の場合、"InvalidStateError" の DOMException を投げ、これらの手順を中止する。
4. event.[[respondWithCalled]] を true に設定する。
5. event の stop propagation flag と event の stop immediate propagation flag を設定する。
6. handlerResponsePromise を event の extend lifetime promises に追加する。
7. event の pending promises count を 1 増やす。
8. Upon rejection （handlerResponsePromise が拒否されたとき）:
   1. payment app failure algorithm を実行し、これらの手順を終了する。
9. Upon fulfillment （handlerResponsePromise が履行されたとき）:
   1. handlerResponse を、value を IDL 値 PaymentHandlerResponse に 変換 したものとする。これが例外を投げた場合、payment app failure algorithm を実行し、これらの手順を終了する。
   2. handlerResponse に必須メンバーがすべて存在し、正しく整形されていることを検証する。
      1. handlerResponse.methodName が存在しない、または event.methodData の値のいずれにも設定されていない場合、 payment app failure algorithm を実行し、これらの手順を終了する。
      2. handlerResponse.details が存在しない、または JSON で直列化可能 でない場合、payment app failure algorithm を実行し、これらの手順を終了する。
      3. shippingRequired を、関連する PaymentRequest の requestShipping の値とする。shippingRequired であり、かつ handlerResponse.shippingAddress が存在しない場合、payment app failure algorithm を実行し、これらの手順を終了する。
      4. shippingRequired であり、かつ handlerResponse.shippingOption が存在しない、または event.shippingOptions の識別子のいずれにも設定されていない場合、payment app failure algorithm を実行し、これらの手順を終了する。
      5. payerNameRequired を、関連する PaymentRequest の requestPayerName の値とする。payerNameRequired であり、 handlerResponse.payerName が存在しない場合、payment app failure algorithm を実行し、これらの手順を終了する。
      6. payerEmailRequired を、関連する PaymentRequest の requestPayerEmail の値とする。payerEmailRequired であり、 handlerResponse.payerEmail が存在しない場合、payment app failure algorithm を実行し、これらの手順を終了する。
      7. payerPhoneRequired を、関連する PaymentRequest の requestPayerPhone の値とする。payerPhoneRequired であり、 handlerResponse.payerPhone が存在しない場合、payment app failure algorithm を実行し、これらの手順を終了する。
   3. handlerResponse の必須メンバーを直列化する（methodName と details は常に必須。 shippingRequired が true のときは shippingAddress と shippingOption も必須。 payerNameRequired、payerEmailRequired、payerPhoneRequired がそれぞれ true のときは、 payerName、payerEmail、payerPhone も必須。):
      1. handlerResponse の各 member について、 serializeMember を StructuredSerialize を handlerResponse.member に対して実行した結果とする。発生した例外は再スローする。
   4. ユーザーエージェントは、[payment-request] で定義される user accepts the payment request algorithm を実行し、手順 9〜15 を以下の手順（または同等の手順）に置き換え MUST 実行する。
      1. 直列化されたメンバーを逆直列化する:
         1. 各 serializeMember について、 member を StructuredDeserialize を serializeMember に対して実行した結果とする。発生した例外は再スローする。
      2. 上記の手順でいずれかの例外が発生した場合、payment app failure algorithm を実行し、これらの手順を終了する。
      3. methodName を、関連する PaymentRequest の response.methodName に代入する。
      4. details を、関連する PaymentReqeust の response.details に代入する。
      5. shippingRequired の場合、関連する PaymentReqeust の shippingAddress 属性に shippingAddress を設定する。そうでない場合は null を設定する。
      6. shippingRequired の場合、関連する PaymentReqeust の shippingOption 属性に shippingOption を設定する。そうでない場合は null を設定する。
      7. payerNameRequired の場合、関連する PaymentReqeust の payerName 属性に payerName を設定する。そうでない場合は null を設定する。
      8. payerEmailRequired の場合、関連する PaymentReqeust の payerEmail 属性に payerEmail を設定する。そうでない場合は null を設定する。
      9. payerPhoneRequired の場合、関連する PaymentReqeust の payerPhone 属性に payerPhone を設定する。そうでない場合は null を設定する。
10. Upon fulfillment または upon rejection のいずれかで handlerResponsePromise が完了したら、次の手順を実行するために マイクロタスクをキューに入れる:
    1. event の pending promises count を 1 減らす。
    2. registration を、 this の relevant global object に関連付けられた service worker の containing service worker registration とする。
    3. registration が null でない場合、Try Activate を registration で呼び出す。

次の例は、支払い要求に応答する方法を示す:

paymentRequestEvent.respondWith(new Promise(function(accept,reject) {
  /* ... processing may occur here ... */
  accept({
    methodName: "https://example.com/pay",
    details: {
      cardHolderName:   "John Smith",
      cardNumber:       "1232343451234",
      expiryMonth:      "12",
      expiryYear :      "2020",
      cardSecurityCode: "123"
     },
    shippingAddress: {
      addressLine: [
        "1875 Explorer St #1000",
      ],
      city: "Reston",
      country: "US",
      dependentLocality: "",
      organization: "",
      phone: "+15555555555",
      postalCode: "20190",
      recipient: "John Smith",
      region: "VA",
      sortingCode: ""
    },
    shippingOption: "express",
    payerEmail: "john.smith@gmail.com",
  });
}));

Web Payments Working Group は、プライバシー上の問題により Payment Request API の初期版から配送先住所および請求先住所のサポートを削除しました（issue 842 を参照）。この機能を引き続きサポートする実装に関する文書を提供するため、作業部会はプライバシー問題に対処することを前提として当該機能を復元しています。その過程で、他の API（例：Content Picker API）の進化に基づき、Payment Request API に変更を加える可能性もあります。

• この API は、ユーザーが登録した支払いハンドラに関する情報を共有しません。オリジンからの情報は、ユーザーの同意がある場合にのみ支払い先と共有されます。
• ユーザーがその支払いハンドラを選択するまでは、ユーザーエージェントは支払い要求の情報をいかなる支払いハンドラとも共有すべきではありません。
• Payment Handler API をサポートするブラウザでは、販売者が URL ベースの支払い方法識別子で PaymentRequest オブジェクトを作成すると、登録済みの支払いハンドラのうち有限のオリジン（支払い方法マニフェストのオリジンと、そのサポートされるオリジン）から、 CanMakePaymentEvent が発火します。このイベントはユーザーがその支払いハンドラを選択する前に発火しますが、トリガー元のオリジン（すなわち販売者サイト）に関する情報を含まないため、直接的にユーザーを追跡する目的では使用できません。
• CanMakePaymentEvent を介したタイミング攻撃のリスクを認識しています:
  • 販売者サイトがバックエンドのチャネル（例：fetch API）を通じて支払いハンドラのオリジンに通知を送り、PaymentRequest オブジェクトの構築を開始する旨を共有する。
  • その後、販売者サイトが PaymentRequest を構築し、インストール済みの支払いハンドラに対して CanMakePaymentEvent を発火させる。
  • 当該支払いハンドラが自オリジンに接続し、サーバー側で両リクエストの突合を試みる。
• ユーザーエージェントは、ユーザーが CanMakePaymentEvent のサポートを無効化できるようにすべきです。
• Payment Handler API をサポートするブラウザでは、登録済みの支払いハンドラのうち、必要に応じて配送先住所や支払人の連絡先情報など販売者が要求するすべての情報を提供できるものに対して CanMakePaymentEvent が発火します。

• この仕様は、支払いハンドラが最初に登録される際に、ユーザーエージェントがどのようにユーザーの同意を確立するかを定義しません。ユーザーエージェントは、登録時にユーザーへ通知したり、プロンプトを表示したりする場合があります。
• ユーザーエージェントはセキュリティ上の理由（例：無効な SSL 証明書）により支払いハンドラの登録を拒否してもよい（MAY）。この場合、ユーザーに通知すべきです（SHOULD）。

• この仕様の目標のひとつは、支払いのために必要なユーザー操作を最小化することです。しかし同時に、ユーザーが支払いを行うことに同意する機会を確保したいとも考えています。支払いハンドラはユーザーとの対話のためにウィンドウを開く必要がない場合があるため、ユーザーエージェントは必要な措置を講じて、ユーザーが (1) 支払い要求が呼び出されたことを認識でき、(2) 販売者が支払いハンドラからの応答を受け取る前に、その支払いハンドラと対話できる機会を持てるようにすべきです。

• 設計上、あるオリジンの支払いハンドラは他のオリジン（例：販売者サイト）とデータを共有します。
• フィッシング攻撃を軽減するため、ユーザーエージェントがユーザーに支払いハンドラのオリジンを明確に示すことが重要です。
• ユーザーエージェントは、ユーザーがクロスオリジンで情報を共有していること、理想的にはどの情報を共有しているかを理解できるよう支援すべきです。

• Service Worker のセキュリティに関する考慮事項を参照してください。
• 支払い方法のセキュリティは本仕様の対象外であり、当該支払い方法をサポートする支払いハンドラによって対処されます。

• 支払い方法の責任主体は、payment method manifest を通じて支払いアプリを認可します。詳細は Handling a CanMakePaymentEvent アルゴリズムを参照してください。
• ユーザーエージェントは、セキュリティ上の問題を引き起こす支払いハンドラを利用可能にする必要はありません。セキュリティ上の問題の例には次のようなものが含まれます:
  • 期限切れ、失効、自己署名などの証明書
  • 混在コンテンツ
  • HTTPS で提供されていたページが非 HTTPS のページへリダイレクトされる
  • セーフブラウジングのデータベースで悪意あるものとして知られている支払いハンドラ

  セキュリティ上の理由により支払いハンドラが利用できない場合、ユーザーエージェントは支払いハンドラの開発者に理由（例：コンソールメッセージ）を提供すべきであり、混乱を避けるためにユーザーへ通知してもよいです。

• Payment method manifests は、特定の支払い方法について支払いアプリを配布する権限をオリジンに付与します。ユーザーエージェントが、支払いハンドラが payment method manifest に記載されたオリジンと一致するかどうかを判定する際には、当該支払いハンドラの service worker registration のスコープ URL を使用します。

• ハイジャックされた支払い先サイトが、詐欺的または不正形式の支払い方法データ（あるいは支払い要求データ）を支払い先サーバーへ送信するシナリオを軽減するため、支払い先サーバーはデータ形式を検証し、サーバー上の権威ある情報（受け入れ可能な支払い方法、合計、表示項目、配送先住所など）と相関付けるべきです。

• 「プライベートブラウジングモード」で Payment Request API が呼び出された場合、ユーザーエージェントは支払いハンドラをプライベートなコンテキストで起動すべきです。これは一般に、サイトが以前に保存された情報へアクセスすることを防ぎます。その結果、ユーザーはオリジンへログインするか、支払い情報を再入力する必要が生じる可能性があります。
• CanMakePaymentEvent イベントは、プライベートブラウジングモードでは発火すべきではありません。ユーザーエージェントは、 respondWith() が false を引数として呼び出されたかのように振る舞うべきです。その結果としてのリスクも認識しています：ある主体が Payment Request API 呼び出しのオリジンと支払いハンドラのオリジンの両方を制御している場合、その主体はユーザーがプライベートブラウジングモードである可能性を推測できるかもしれません。