From 7527c1251730ba592afba69acb2bb8471312476b Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Wed, 11 Jan 2017 18:20:29 -0500 Subject: [PATCH] Straighten out the payment method data flow (#382) This fixes #338 and helps with #307 by stating more explicitly how the data member of PaymentMethodDetails is serialized to a string, stored, and later passed to the appropriate payment app. Along the way, this fixes #354. This does not completely fix #307, as the problematic JSON-serializable concept is still used for PaymentDetailsModifier (and is still not used by any part of the processing model; that's #346). --- index.html | 226 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 136 insertions(+), 90 deletions(-) diff --git a/index.html b/index.html index 21270e2c..bbf7c928 100644 --- a/index.html +++ b/index.html @@ -125,12 +125,19 @@

every transaction: the merchant (e.g., an online web store), the buyer represented by the user agent (e.g., the user buying from the online web store), and the Payment Method (e.g., credit + "payment method|payment methods">payment method (e.g., credit card). Information necessary to process and confirm a transaction is - passed between the Payment Method and the merchant via the + passed between the payment method and the merchant via the user agent with the buyer confirming and authorizing as necessary across the flow.

+

+ The details of how to fulfill a payment request for a given payment + method are handled by payment apps. In this specification, + these details are left up to the user agent, but future + specifications may expand on the processing model in more detail. +

In addition to better, more consistent user experiences, this also enables web sites to take advantage of more secure payment schemes @@ -276,13 +283,15 @@

The PaymentRequest is constructed using the supplied - methodData list including any payment method - specific data, the payment details, and the - payment options. + methodData list including any payment method + specific data, the payment + details, and the payment options. The + methodData supplied to the PaymentRequest + constructor SHOULD be in the order of preference of the caller.

- The methodData sequence contains + The methodData sequence contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the web site accepts and any associated payment method specific @@ -305,7 +314,7 @@

const request = new PaymentRequest(methodData, details, options);

- The details object contains information about the + The details object contains information about the transaction that the user is being asked to complete such as the line items in an order.

@@ -329,7 +338,7 @@

const request = new PaymentRequest(methodData, details, options);

- The options object contains information about what + The options object contains information about what options the web page wishes to use from the payment request system. 

@@ -364,6 +373,8 @@ 

               
             
           
+          
  • Let parsedMethodData be an empty list.
+          
    • 
           
  • Process payment methods:
             
      
               
    1. If the length of the methodData sequence is zero,
@@ -379,12 +390,17 @@ 
      
                     method needs to include at least one payment method
                     identifier.
                   
      2. 
-                  
    2. If the data
-                  member of paymentMethod is present, but
-                  paymentMethod.data is not a
-                  JSON-serializable object, then throw a
-                  TypeError.
+                  
    3. Let parsedData be the result of
+                  JSON-serializing
+                    paymentMethod.data
+                    into a string, if the data member of
+                    paymentMethod is present, or null if it is not.
+                    Rethrow any exceptions.
+                  
      4. 
+                  
    4. Add the tuple (paymentMethod.supportedMethods,
+                  parsedData) to parsedMethodData.
                   
      5. 
                 
    
               
    • 
@@ -558,18 +574,8 @@ 
    
           
           
  • Set request.[[\details]] to details.
           
    • 
-          
  • 
-            
    
-              Set request.[[\methodData]] to
-              methodData.
-            
    
-            
    
-              The methodData supplied to the PaymentRequest
-              constructor SHOULD be in the order of preference of the caller.
-              Implementations MAY show payment methods in this order if
-              possible but SHOULD prioritize the preference of the user when
-              presenting payment methods.
-            
    
+          
  • Set request.[[\parsedMethodData]] to
+          parsedMethodData.
           
    • 
           
  • Set the value of request's shippingOption attribute to 
@@ -638,22 +644,36 @@ 
    
           
  • Return acceptPromise and perform the remaining steps
           in parallel.
           
    • 
-          
  • Let supportedMethods be the union of all the
-          supportedMethods sequences from each
-          PaymentMethodData in the
-          request.[[\methodData]] sequence.
-          
    • 
-          
  • Let acceptedMethods be supportedMethods
-          with all identifiers removed that the user agent does not
-          accept.
+          
  • For each paymentMethod in
+          request.[[\parsedMethodData]]:
+            
      
+              
    1. Consult the appropriate payment apps to see if they
+              support any of the payment method identifiers given by the
+              first element of the paymentMethod tuple, passing
+              along the data string given by the second element of the tuple in
+              order to help them determine their support.
+              
      2. 
+            
    
           
    • 
-          
  • If the length of acceptedMethods is zero, then reject
-          acceptPromise with a NotSupportedError.
+          
  • If this consultation produced no supported method of paying, then
+          reject acceptPromise with a NotSupportedError, and
+          abort this algorithm.
           
    • 
-          
  • Show a user interface to allow the user to interact with the
-          payment request process. The acceptPromise will later be
-          resolved by the user accepts the payment request algorithm
-          through interaction with the user interface.
+          
  • 
+            
    
+              Otherwise, show a user interface to allow the user to interact
+              with the payment request process, using those payment apps
+              and payment methods which the above step identified as
+              feasible. The user agent MAY show payment methods in the order
+              given by supportedMethods, but SHOULD prioritize the
+              preference of the user when presenting payment methods and
+              applications.
+            
    
+            
    
+              The acceptPromise will later be resolved by the
+              user accepts the payment request algorithm through
+              interaction with the user interface.
+            
    
           
    • 
         
       
@@ -830,10 +850,12 @@ 
    
           
           
             
-              [[\methodData]]
+              [[\parsedMethodData]]
             
             
-              The methodData supplied to the constructor.
+              The methodData supplied to the constructor, but
+              represented as tuples containing supported methods and a string
+              or null for data (instead of the original object form).
             
           
           
@@ -920,9 +942,9 @@ 
    
           data
         
         
    
-          data is a
-          JSON-serializable object that provides optional information
-          that might be needed by the supported payment methods.
+          data is an object that
+          provides optional information that might be needed by the supported
+          payment methods. If supplied, it will be JSON-serialized.
         
    
       
     
@@ -1055,7 +1077,8 @@ 
    
           
    
             The shippingOptions field is only used if the
             PaymentRequest was constructed with PaymentOptions
-            requestShipping set to true.
+            requestShipping set
+            to true.
           
    
           
    
             If the sequence has an item with the selected field
@@ -1529,11 +1552,10 @@ 
    
           details
         
         
    
-          A JSON-serializable object that provides a payment
-          method specific message used by the merchant to process the
-          transaction and determine successful fund transfer. This data is
-          returned by the payment method specific code that satisfies
-          the payment request.
+          An object that provides a payment method specific message used
+          by the merchant to process the transaction and determine successful
+          fund transfer. This data is returned by the payment method
+          specific code that satisfies the payment request.
         
    
         
    
           shippingAddress
@@ -2159,52 +2181,68 @@ 
    
           action. The user agent user interface should ensure that this
           never occurs.
           
    • 
-          
  • If the requestShipping value of
+          
  • If the requestShipping value of
           request.[[\options]] is true, then if the
-          shippingAddress attribute of request is
-          null or if the shippingOption attribute of
-          request is null, then terminate this
-          algorithm and take no further action. This should never occur.
+          shippingAddress
+          attribute of request is null or if the shippingOption attribute of 
+            request is null, then terminate this algorithm and take no
+            further action. This should never occur.
           
    • 
           
  • Let response be a new PaymentResponse.
           
    • 
-          
  • Set the methodName attribute value of
-          response to the payment method identifier for the
-          payment method that the user selected to accept the payment.
+          
  • Set the methodName
+          attribute value of response to the payment method
+          identifier for the payment method that the user selected
+          to accept the payment.
           
    • 
-          
  • Set the details attribute value of
-          response to a JSON-serializable object containing
-          the payment method specific message that will be used by the
+          
  • Set the details
+          attribute value of response to an object containing the
+          payment method specific message that will be used by the
           merchant to process the transaction. The format of this response will
-          be defined for each payment method.
-          
    • 
-          
  • If the requestShipping value of
-          request.[[\options]] is true, then copy the 
-            shippingAddress attribute of request to the
-            shippingAddress
-            attribute of response.
-          
    • 
-          
  • If the requestShipping value of
-          request.[[\options]] is true, then copy the 
-            shippingOption attribute of request to the
-            shippingOption
-            attribute of response.
+          be defined for each payment method, and the contents of the
+          response will be determined by the payment app used. If the
+          response is provided as a Web IDL dictionary, first convert it to an
+          ECMAScript object.
+          
    • 
+          
  • If the requestShipping value of
+          request.[[\options]] is true, then:
+            
      
+              
    1. Set the shippingAddress attribute of
+              request to the shippingAddress attribute
+              of response.
+              
      2. 
+              
    2. Set the shippingOption attribute of
+              request to the shippingOption attribute of
+              response.
+              
      3. 
+            
    
           
    • 
-          
  • If the requestPayerName value of
-          request.[[\options]] is true, then set the
-          payerName attribute of
-          response to the payer's name provided by the user.
+          
  • If the requestPayerName value of 
+            request.[[\options]] is true, then set the payerName attribute of
+            response to the payer's name provided by the user.
           
    • 
-          
  • If the requestPayerEmail value of
+          
  • If the requestPayerEmail value of
           request.[[\options]] is true, then set the
           payerEmail attribute of
           response to the payer's email address selected by the
           user.
           
    • 
-          
  • If the requestPayerPhone value of
+          
  • If the requestPayerPhone value of
           request.[[\options]] is true, then set the
-          payerPhone attribute of response to the
-          payer's phone number selected by the user.
+          payerPhone attribute of
+          response to the payer's phone number selected by the user.
           
    • 
           
  • Set response.[[\completeCalled]] to false.
           
    • 
@@ -2284,9 +2322,8 @@ 
    
         
         
    
           The term Payment Method
-          Identifier is defined by the Payment Method Identifiers
-          specification [[!METHOD-IDENTIFIERS]].
+          "payment method identifier|payment method identifiers">payment method
+          identifier is defined by [[!METHOD-IDENTIFIERS]].
         
    
         
    
           HTML 5.1
@@ -2345,9 +2382,17 @@ 
    
           JSON.parse are defined by [[!ECMA-262-2015]].
           
    
             The term JSON-serializable object used in this
-            specification means an object that can be serialized to a string
-            using JSON.stringify and later deserialized back to an
-            object using JSON.parse with no loss of data.
+            specification is not well defined; see issue
+            #307.
+          
    
+          
    
+            The term JSON-serialize
+            applied to a given object means to run the algorithm specified by
+            the original value of the JSON.stringify function on the
+            supplied object, passing the supplied object as the sole argument,
+            and return the resulting string. This can throw an exception.
           
    
         
         
    
@@ -2437,7 +2482,8 @@ 
    
           
    
           
    
             The algorithm for converting an ECMAScript value to a
-            dictionary is defined by [[!WEBIDL-2]].
+            dictionary and for converting a dictionary to an
+            ECMAScript value is defined by [[!WEBIDL-2]].