diff --git a/proposals/paymentapps/payment-apps.html b/proposals/paymentapps/payment-apps.html index ffdcca9..25f0122 100644 --- a/proposals/paymentapps/payment-apps.html +++ b/proposals/paymentapps/payment-apps.html @@ -375,6 +375,7 @@

The PaymentApp dictionary

DOMString name; URLString start_url; sequence<DOMString> enabled_methods; + sequence<DOMString> communication_methods; };
@@ -409,14 +410,27 @@

- -

enabled_methods

+

enabled_methods member

- The enabled_methods member - lists the payment method identifiers of the payment methods + The enabled_methods + member lists the payment method identifiers of the payment methods that can be processed by the payment app.

+
+

communication_methods member

+

+ The communication_methods + member is a list of strings that defines how the user agent + can communicate with the payment app. +

+

+ The communication_methods list must contain one or both of the + values "javascript" and "http". If the member does + not exist or does not contain any of these two values, it will default to + the list that contains the single element "javascript". +

+

registerPaymentApp()

@@ -464,193 +478,152 @@

Processing Payment Requests

selection algorithm as defined in the Payment Request API [[!PAYMENT-REQUEST-API]] it must pass the payment request to the payment app to be processed.

-

The user agent does this by, converting the payment - request into a JSON serialized object, executing an HTTP POST - request against the start_url of the - payment app.

-

At a minimum the user agent MUST handle the following two - responses from the payment app:

-
    -

  1. - An HTML response that MUST be rendered by the user agent. -

    -

    - When the browser gets HTML back from the payment app it must render this - UI for the user to interact with the payment app. Should this be in an iframe, - in a special modal dialogue or just a new tab? Is this an implementation - detail? -

    -
    2. -
  2. A JSON serialized payment response which is converted by the - user agent into a PaymentResponse object. The - Promise that was returned to the payee website when calling - PaymentRequest.show MUST resolve to this - PaymentResponse.
    3. -
-
-

Converting the PaymentRequest into JSON.

-

Before the PaymentRequest can be submitted to the - payment app it must be converted into a JSON serialized - string.

-

The steps to convert the PaymentRequest to - JSON are given by the following algorithm. The algorithm - takes a PaymentRequest (request) as input and - returns a string.

-
-

- The algortihm for this conversion will depend on the outcome of - discussions around the shape of the PaymentRequest API. This - algorithm may also sit in the core messages spec. -

-

- The fact that there are elements of this specification that can't be decided - until the Payment Request API is decided is another indication that the two - should be combined or have a normative dependancy. -

-
-
+

How the user agent does this, depends on the communication method + selected for communicating between the user agent and the + payment app.

-

Sending the payment request to the Payment - App

-

The steps to submit the payment request to the payment app - are given by the following algorithm:

-
    -
  1. Let payment request be the string that is the - outcome of the steps to convert the PaymentRequest - to JSON.
    2. -
  2. Let payment app be the registered payment app - selected by the user to process this PaymentRequest. -
    We - should get input form Web Platform and WebAppSec on how to best - construct this request.
    -
    3. -
  3. Let request be a new [[!FETCH]] request, - whose members are set to the following values: - - - - - - - - - - - - - - - - - - - - - -
    MemberValue
    URLThe value of the start_url member of payment - app
    methodThe value "POST"
    header list - - - - - -
    Accepttext/html;application/json
    -
    bodyThe value of payment request
    -
    4. -
  4. Await the result of performing a fetch with - request, letting response be the result.
    5. -
  5. If response is a network error, terminate - this algorithm.
    6. -
  6. -

    Switch on response's MIME type

    -
    -
    text/html
    -
    -
      -
    1. Execute the steps to render a web based payment app - using response as input.
      2. -
    -
    -
    application/json
    -
    -
      -
    1. -
      Should the - JSON encoded PaymentRequest and PaymentResponse be JSON-LD with an - associated @context?
      -
      2. -
    2. If response's body is a JSON encoded - PaymentResponse execute the steps to create a - PaymentResponse from JSON using the - response's body as input.
      3. -
    3. Otherwise reject the Promise created during PaymentRequest.show - with an error.
      4. -
    -
    -
    -
    7. -
+

Selecting a communication method

+

The user agent may select any one communication method from the + intersection of the communication_methods manifest + member and the communication methods supported by the user agent.

-

Launching the Payment App

-

Unless the selected payment app is built into the user - agent or uses a proprietary mechanism for launching and - interfacing with the payment app, the user agent MUST - launch the payment app based upon the response it gets from - submitting the PaymentRequest.

-

The MIME Type and other signals are used to determine how the - app is launched and what type of app is launched.

+

Communicating via javascript

+

This communication method is suitable for Browser-based payment apps that + display an HTML user interface. They communicate using the following + javascript API:

+ +
+                partial interface Navigator {
+                    readonly attribute PaymentsApi payments;
+                };
+
+                partial interface PaymentsApi {
+                    PaymentRequest getRequest();
+                    Promise<boolean> submitPaymentResponse(PaymentResponse response);
+                };
+
-

Web Based Payment App with HTML interface

-

If the payment app is a web application with an HTML-based user - interface then the response will have a MIME Type of - text/html.

-

If a user agent receives a response with a MIME - Type of text/html it MUST assume that the - response body is the HTML that must be rendered as the user - interface of the payment app.

+

Sending the Payment Request to the Payment App

The user agent MUST execute the steps to render a - web based payment app as given by the following algorithm. - The algorithm takes a [[!FETCH]] Response - (response) as input:

+ web based payment app as given by the following algorithm.

  1. Create a new top-level browsing context in a new tab, window or dialogue as new context.
    2. -
  2. Render the response in the new - context.
    3. +
  3. Load the web page pointed to by start_url + in the new context.
    4. +
+

The payment app can retrieve the payment request from the browser by + calling getRequest.

+
+
+

Receiving the Payment Response from the Payment App

+

The user will interact directly with web based payment + apps in the context created for this purpose + by the user agent.

+

When the payment app is ready to do so, it must submit a + PaymentResponse to the user agent that can be + returned to the website that submitted the initial + PaymentRequest. It does this by calling + submitPaymentResponse.

+
+
+
+

Communicating over HTTP

+

This communication method is intended for payment apps that do not require + a user interface, and communicate the payment requests and responses as JSON + over HTTP.

+
+

Converting the Payment Request into JSON

+

Before the PaymentRequest can be submitted to the + payment app it must be converted into a JSON serialized + string.

+

The steps to convert the PaymentRequest to + JSON are given by the following algorithm. The algorithm + takes a PaymentRequest (request) as input and + returns a string.

+
+

+ The algortihm for this conversion will depend on the outcome of + discussions around the shape of the PaymentRequest API. This + algorithm may also sit in the core messages spec. +

+

+ The fact that there are elements of this specification that can't be decided + until the Payment Request API is decided is another indication that the two + should be combined or have a normative dependancy. +

+
+
+
+

Sending the Payment Request to the Payment App

+

The steps to submit the payment request to the payment app + are given by the following algorithm:

+
    +
  1. Let payment request be the string that is the + outcome of the steps to convert the PaymentRequest + to JSON.
    2. +
  2. Let payment app be the registered payment app + selected by the user to process this PaymentRequest. +
    We + should get input form Web Platform and WebAppSec on how to best + construct this request.
    +
    3. +
  3. Let request be a new [[!FETCH]] request, + whose members are set to the following values: + + + + + + + + + + + + + + + + + + + + + +
    MemberValue
    URLThe value of the start_url member of payment + app
    methodThe value "POST"
    header list + + + + + +
    Acceptapplication/json
    +
    bodyThe value of payment request
    +
    4. +
  4. Await the result of performing a fetch with + request, letting response be the result.
    5. +
  5. If response is a network error, terminate + this algorithm.
    6. +
  6. +
    Should the + JSON encoded PaymentRequest and PaymentResponse be JSON-LD with an + associated @context?
    +
    7. +
  7. If response's body is a JSON encoded + PaymentResponse execute the steps to create a + PaymentResponse from JSON using the + response's body as input.
    8. +
  8. Otherwise reject the Promise created during PaymentRequest.show + with an error.
-
-

Accepting the PaymentResponse

-
-                    partial interface Navigator {
-                        readonly attribute PaymentsApi payments;
-                    };
-
-                    partial interface PaymentsApi {
-                        Promise<boolean> submitPaymentResponse (PaymentResponse response);
-                    };
-
-
-
-

The user will interact directly with web based payment - apps in the context created for this purpose - by the user agent.

-

When the payment app is ready to do so, it must submit a - PaymentResponse to the user agent that can be - returned to the website that submitted the initial - PaymentRequest. It does this by calling - submitPaymentResponse.

-
-

Autonomous Payment App services with no user interface

-

If the payment app is a web service that requires no user - interface then the response must set the Content-Type - header to the value application/json and the response - body should be a JSON serialized payment response object.

+

Converting JSON into a Payment Response

The steps to create a PaymentResponse from JSON are given in the following algorithm:

Autonomous Payment App services with no user interface
-

Resolving the PaymentResponse Promise

+

Resolving the Payment Response promise

The user agent must return a PaymentResponse to the website that originally initiated the PaymentRequest. The steps for returning the PaymentResponse are @@ -669,15 +642,12 @@

Resolving the PaymentResponse Promise

PaymentResponse.
  • Let promise be the Promise that was created by PaymentRequest.show.
    • -
  • If a web based payment app called - submitPaymentResponse then - set response equal to the first parameter passed to - that method.
    • -
  • Otherwise, if the steps to submit the - payment request to the payment app resulted in the - return of a JSON encoded PaymentResponse then set - response to the result of running the steps to create - a PaymentResponse from JSON.
    • +
  • If the user agent communicates with the payment app + via javascript, then set response to the first parameter + passed to the submitPaymentResponse method.
    • +
  • Otherwise, if communicating via HTTP then set response + to the result of running the steps to create a PaymentResponse + from JSON.
  • Resolve promise with response.