From 77e3f547385667e0e1550ce13e71da9a8df9816c Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Wed, 14 Dec 2016 17:07:49 -0500 Subject: [PATCH] Straighten out the payment method data flow 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 | 149 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 89 insertions(+), 60 deletions(-) diff --git a/index.html b/index.html index d4e330e2..172fb870 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 @@ -274,13 +281,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 @@ -303,7 +312,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.

@@ -327,7 +336,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. 

@@ -359,6 +368,8 @@ 

               
             
           
+          
  • Let parsedMethodData be an empty list.
+          
    • 
           
  • Process payment methods:
             
      
               
    1. If the length of the methodData sequence is zero,
@@ -374,12 +385,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. 
                 
    
               
    • 
@@ -553,18 +569,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 
@@ -633,22 +639,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.
+            
    
           
    • 
         
       
@@ -765,10 +785,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).
             
           
           
@@ -855,9 +877,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.
         
    
       
     
@@ -1456,11 +1478,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
@@ -2027,10 +2048,11 @@ 
    
           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
-          merchant to process the transaction. The format of this response will
-          be defined for each payment method.
+          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, and the contents of the response will be
+            determined by the payment app used.
           
    • 
           
  • If the requestShipping value of
           request.[[\options]] is true, then copy the 
@@ -2138,9 +2160,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
@@ -2199,9 +2220,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.