ウェブベース決済ハンドラー API

加盟店が show() メソッドを呼び出した時点で Web ベース決済ハンドラーが未登録で ある場合、ユーザーエージェントは取引中にこの Web ベース決済 ハンドラーを登録すること （「just-in-time」）をユーザーに許可してもよい。

この節の残りの内容は非規範的です。

ユーザーエージェントは、加盟店が要求した URL ベースの payment method identifier を通じて見つかる payment method manifest から Web ベース決済ハンドラー情報を導出することで、適時インストールを 実行してもよい。

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

paymentManager 属性は、Web ベース決済 ハンドラー管理機能を公開する。

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

PaymentManager は、Web-based payment handler が サポートする委任を管理するために用いられる。

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

"shippingAddress"

Web ベース決済ハンドラーは、必要に応じて配送先住所を提供する。

"payerName"

Web ベース決済ハンドラーは、必要に応じて支払人の氏名を提供する。

"payerPhone"

Web ベース決済ハンドラーは、必要に応じて支払人の電話番号を提供する。

"payerEmail"

Web ベース決済ハンドラーは、必要に応じて支払人のメールアドレスを提供する。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

CanMakePaymentEvent は、 Web ベース決済ハンドラーが支払いリクエストに応答可能かどうかを 示すシグナルとして使用される。

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

PaymentRequest を受信すると、user agent は MUST 次の手順を実行する:

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

4. Fire Functional Event により "canmakepayment" を CanMakePaymentEvent を用いて registration 上で発火する。

PaymentMethodData と、 payment method identifier に一致する Web ベース決済ハンドラーが与えられたとき、このアルゴリズムは、 その Web ベース決済ハンドラーが支払いに使用可能であれば true を返す:

1. methodName を、 payment method identifier の文字列であり、 PaymentMethodData に指定されたものとする。
2. methodData を、 PaymentMethodData の支払い手段固有データとする。
3. paymentHandlerOrigin を、 origin とし、 Web ベース決済ハンドラーの ServiceWorkerRegistration の scope URL の origin とする。
4. paymentMethodManifest を、 ingested され、 parsed された payment method manifest とし、 methodName に対するものとする。
5. methodName が URL-based payment method identifier であり、 paymentMethodManifest における "*" 文字列の supported origins を持つ場合、 true を返す。
6. そうでなく、 URL-based payment method identifier methodName が paymentHandlerOrigin と同じ origin を持つ場合、 Web ベース決済ハンドラー内で CanMakePaymentEvent を発火し、その結果を返す。
7. そうでなく、 paymentMethodManifest における supported origins が、 paymentHandlerOrigin を含む origin の順序付き集合である場合、Web ベース決済ハンドラー内で CanMakePaymentEvent を発火し、 その結果を返す。
8. そうでなければ、false を返す。

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

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

PaymentRequestDetailsUpdate は、Web ベース決済ハンドラー内で ユーザーが支払い方法、配送先住所、または配送オプションを選択した結果として生じる、 更新された合計額（必要に応じて modifiers および shipping options を含む） と、起こり得るエラーを含む。

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() によって受信し、 その後ユーザーが Web ベース決済ハンドラーを選択したとき、 user agent は MUST 次の手順を実行する:

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

3. Fire Functional Event により "paymentrequest" を PaymentRequestEvent を用いて registration 上で発火し、 次のプロパティを持たせる:

   topOrigin

   最上位レベルの payee Web ページの origin の 直列化。

   paymentRequestOrigin

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

   methodData

   MethodData Population Algorithm を実行した結果。

   modifiers

   Modifiers Population Algorithm を実行した結果。

   total

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

   paymentRequestId

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

   paymentOptions

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

   shippingOptions

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

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

   1. dispatchedEvent の extend lifetime promises 内のすべての promise が解決されるのを待つ。
   2. Web-based payment handler が PaymentHandlerResponse を提供していない場合、 Promise を、 PaymentRequest.show() によって生成されたものについて、 "OperationError" の DOMException で reject する。

1. event を、この PaymentRequestEvent とする。
2. event の isTrusted 属性が false の場合、 "InvalidStateError" の DOMException で reject された Promise を返す。
3. request を、この PaymentRequest とし、 この PaymentRequestEvent を引き起こしたものとする。
4. url を、url 引数を 解析 した結果とする。
5. url の解析が例外を投げた場合、その例外で reject された Promise を返す。
6. url が about:blank の場合、 TypeError で reject された Promise を返す。
7. url の origin が、Web ベース決済ハンドラーに関連付けられた service worker の origin と同じでない場合、 null で resolve された Promise を返す。
8. promise を、新しい Promise とする。
9. promise を返し、残りの手順を並列に実行する:
10. event.[[windowClient]] が null でない場合、次を実行する:
    1. event.[[windowClient]].visibilityState が "unloaded" でない場合、 "InvalidStateError" の DOMException で promise を reject し、これらの手順を中止する。
11. newContext を、新しい top-level browsing context とする。
12. Navigate により、例外を有効にし、replacement を有効にして、 newContext を url に遷移させる。
13. その navigation が例外を投げた場合、その例外で promise を reject し、これらの手順を中止する。
14. newContext の origin が、Web ベース決済ハンドラーに関連付けられた service worker client の origin と同じでない場合、 次を実行する:
    1. promise を null で resolve する。
    2. これらの手順を中止する。
15. client を、 newContext を引数として create window client アルゴリズムを実行した結果とする。
16. event.[[windowClient]] を client に設定する。
17. promise を client で resolve する。

user agent は、対応する respondWith 関数に提供された Promise が解決されることで、Web ベース決済ハンドラーからの成功応答を受け取る。 これは PaymentRequestEvent インターフェースに属する。 アプリケーションは、支払い応答を含む PaymentHandlerResponse インスタンスで Promise を解決することが期待される。ユーザー取消しまたは エラーの場合、アプリケーションは Promise を reject することで 失敗を通知してよい。

PaymentHandlerResponse は、次の辞書を用いて伝達される:

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

このアルゴリズムが methodName と methodDetails パラメーターで呼び出されたとき、 user agent は MUST 次の手順を実行する:

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

このアルゴリズムが shippingAddress または shippingOption で呼び出されたとき、 user agent は MUST 次の手順を実行する:

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

このアルゴリズムが event と handlerResponsePromise パラメーターで呼び出されたとき、 user agent は 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. reason を伴う handlerResponsePromise の reject 時:
   1. reason を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
9. handlerResponsePromise の fulfill 時:
   1. handlerResponse を、value を IDL 値に変換 した PaymentHandlerResponse とする。これが例外を投げた場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
   2. 必要なすべてのメンバーが handlerResponse に存在し、かつ整形式であることを 検証する。
      1. handlerResponse.methodName が存在しない、または event.methodData の値のいずれかに設定されていない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      2. handlerResponse.details が存在しない、または JSON-serializable でない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      3. shippingRequired を、関連付けられた PaymentRequest の requestShipping 値とする。これはその paymentOptions のものである。 shippingRequired が true で、かつ handlerResponse.shippingAddress が存在しない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、これらの手順を終了する。
      4. shippingRequired が true で、かつ handlerResponse.shippingOption が存在しない、または event.shippingOptions から得られる shipping options identifiers のいずれにも 設定されていない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      5. payerNameRequired を、関連付けられた PaymentRequest の requestPayerName 値とする。これはその paymentOptions のものである。 payerNameRequired が true で、かつ handlerResponse.payerName が存在しない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      6. payerEmailRequired を、関連付けられた PaymentRequest の requestPayerEmail 値とする。これはその paymentOptions のものである。 payerEmailRequired が true で、かつ handlerResponse.payerEmail が存在しない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      7. payerPhoneRequired を、関連付けられた PaymentRequest の requestPayerPhone 値とする。これはその paymentOptions のものである。 payerPhoneRequired が true で、かつ handlerResponse.payerPhone が存在しない場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
   3. handlerResponse の必要メンバーを serialize する （methodName と details は常に必須。 shippingRequired が true のとき shippingAddress と shippingOption が必須。 payerNameRequired、 payerEmailRequired、 payerPhoneRequired が true のとき、それぞれ payerName、payerEmail、 payerPhone が必須。):
      1. handlerResponse 内の各 member について、 serializeMember を StructuredSerialize に handlerResponse.member を与えた結果とする。 あらゆる例外を再送出する。
   4. user agent は MUST [payment-request] で定義される user accepts the payment request algorithm を実行し、 その 9-15 ステップを、これらの手順または同等の手順で 置き換える:
      1. serialize されたメンバーを deserialize する:
         1. 各 serializeMember について、 member を StructuredDeserialize に serializeMember を与えた結果とする。 あらゆる例外を再送出する。
      2. 上記の手順で何らかの例外が発生した場合、 "OperationError" の DOMException を用いて payment app failure algorithm を実行し、 これらの手順を終了する。
      3. methodName を、関連付けられた PaymentRequest の response.methodName に代入する。
      4. details を、関連付けられた PaymentReqeust の response.details に代入する。
      5. shippingRequired が true の場合、 関連付けられた PaymentReqeust の shippingAddress 属性を shippingAddress に設定する。 そうでなければ null に設定する。
      6. shippingRequired が true の場合、 関連付けられた PaymentReqeust の shippingOption 属性を shippingOption に設定する。 そうでなければ null に設定する。
      7. payerNameRequired が true の場合、 関連付けられた PaymentReqeust の payerName 属性を payerName に設定する。 そうでなければ null に設定する。
      8. payerEmailRequired が true の場合、 関連付けられた PaymentReqeust の payerEmail 属性を payerEmail に設定する。 そうでなければ null に設定する。
      9. payerPhoneRequired が true の場合、 関連付けられた PaymentReqeust の payerPhone 属性を payerPhone に設定する。 そうでなければ null に設定する。
10. handlerResponsePromise の fulfill 時 または reject 時 に、 次の手順を実行する microtask を queue する:
    1. event の pending promises count を 1 減らす。
    2. registration を、 this の relevant global object に関連付けられた service worker の containing service worker registration とする。
    3. registration が null でない場合、 registration を用いて Try Activate を呼び出す。

次の例は、支払いリクエストに応答する方法を示す:

paymentRequestEvent.respondWith(new Promise(function(accept,reject) {
  /* ... ここで処理が行われることがある ... */
  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",
  });
}));

このアルゴリズムが reason で呼び出されたとき、 user agent は MUST 次の手順を実行する:

1. reason が "OperationError" の DOMException である場合、 [payment-request] で定義される Payment handler indicates an internal error algorithm を実行する。
2. そうでなければ、 [payment-request] で定義される user aborts the payment request algorithm を実行する。
   注

   この仕様の以前の版では、 payment app failure algorithm が 呼び出されたときに何が起こるかを定義していなかった。実際には、 実装者は user aborts the payment request algorithm が実行されたかのように 振る舞っていた。 可能な限り後方互換性を維持しつつ、Web ベース決済ハンドラーが 内部エラーを示す方法を導入するために、この仕様では現在、 "OperationError" の DOMException 以外のすべての reason 値を user abort に対応付けている。 将来の版のこの仕様では、追加の処理対象値が導入される可能性がある。

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

• この API は、ユーザーに登録された Web ベース決済ハンドラーに関する情報を共有しない。 オリジンからの情報は、ユーザーの同意がある場合にのみ payee と共有される。
• user agent は、ユーザーがその決済ハンドラーを選択するまで、 いかなる Web ベース決済ハンドラーとも支払いリクエスト情報を 共有すべきではない。
• Web-based Payment Handler API をサポートするブラウザーでは、 merchant が URL ベースの支払い方法識別子を用いて PaymentRequest オブジェクトを作成すると、 CanMakePaymentEvent が、 有限個のオリジン集合に属する登録済み Web ベース決済ハンドラーで 発火する。すなわち、その支払い方法マニフェストのオリジンと、 その supported origins である。 このイベントは、ユーザーがその決済ハンドラーを選択する前に 発火するが、発火元オリジン（すなわち merchant website）に 関する情報は含まないため、これを用いてユーザーを直接追跡する ことはできない。
• 我々は、 CanMakePaymentEvent を介したタイミング攻撃のリスクを認識している:
  • merchant website はバックエンドチャネル （例: fetch API）を通じて Web ベース決済ハンドラーの オリジンへ通知を送り、これから PaymentRequest オブジェクトを 構築しようとしていることを共有する。
  • その後 merchant website は PaymentRequest を構築し、 インストール済み Web ベース決済ハンドラーに対して CanMakePaymentEvent の発火を 引き起こす。
  • その Web ベース決済ハンドラーは自身のオリジンに連絡し、 サーバー側で 2 つのリクエストを結び付けようとする。
• user agent は、ユーザーが CanMakePaymentEvent のサポートを無効化できるようにすべきである。
• Web-based Payment Handler API をサポートするブラウザーでは、 CanMakePaymentEvent は、 配送先住所や支払人の連絡先情報を含む、merchant が要求する すべての情報を必要に応じて提供できる登録済み Web ベース決済ハンドラーで発火する。

• この仕様は、Web ベース決済ハンドラーが最初に登録される際に、 user agent がどのようにユーザー同意を確立するかを定義しない。 user agent は、登録中にユーザーへ通知および／または プロンプトを表示してよい。
• user agent は、セキュリティ上の理由 （例: 無効な SSL 証明書）により Web ベース決済ハンドラー登録を 拒否してもよく、これが発生した場合にはユーザーへ通知する べきである。

• この仕様の目標の一つは、支払いを行うために必要な ユーザー操作を最小化することである。しかし同時に、 ユーザーが支払い実行に同意する機会を確保したい。 Web ベース決済ハンドラーはユーザー操作のためにウィンドウを 開くことを要求されないため、user agent は次のことを 確実にするために必要な手段を講じるべきである。 すなわち、ユーザーが (1) 支払いリクエストが呼び出されたことを認識でき、 (2) merchant がその決済ハンドラーから応答を受け取る前に、 Web ベース決済ハンドラーと対話する機会を持てること。

• 設計上、あるオリジンの Web ベース決済ハンドラーは、 別のオリジン（例: merchant site）とデータを共有する。
• フィッシング攻撃を軽減するためには、user agent が Web ベース決済ハンドラーのオリジンをユーザーに明確に示すことが 重要である。
• user agent は、ユーザーが自分の情報を クロスオリジンで共有していること、理想的には 何の情報を共有しているかを理解できるよう支援すべきである。

• Service Worker security considerations を参照
• 支払い方法のセキュリティはこの仕様の範囲外であり、 それらの支払い方法をサポートする Web ベース決済ハンドラーにより 扱われる。

• 支払い方法に責任を持つ当事者は、 payment method manifest を通じて決済 アプリを認可する。詳細は Handling a CanMakePaymentEvent アルゴリズムを参照。
• user agent は、セキュリティ上の問題をもたらす Web ベース決済ハンドラーを利用可能にすることを要求されない。 セキュリティ上の問題には、次のようなものが含まれ得る:
  • 期限切れ、失効済み、自己署名などの証明書。
  • Mixed content
  • HTTPs 経由で利用可能なページが、そうでないページへ リダイレクトすること。
  • 決済ハンドラーが safe browsing database により 悪意あるものと知られていること

  セキュリティ上の理由で Web ベース決済ハンドラーが利用不可と なる場合、user agent はその理由を Web ベース決済ハンドラーの 開発者に提供すべきであり（例: console messages を通じて）、 また混乱を避けるためにユーザーへ通知してもよい。

• Payment method manifests は、特定の支払い方法に対して 決済アプリを配布するオリジンを認可する。 user agent が Web ベース決済ハンドラーが payment method manifest に記載されたオリジンと一致するかどうかを 判定する際、user agent は Web ベース決済ハンドラーの service worker registration の scope URL を使用する。

• 乗っ取られた payee site が、不正または不正形式の payment method data（あるいは支払いリクエストデータ）を payee のサーバーへ送信するシナリオを軽減するために、 payee のサーバーはデータ形式を検証し、受け入れられた 支払い方法、合計、表示項目、配送先住所などの サーバー上の正当な情報とそのデータを照合すべきである。

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