PaymentRequest constructor

The PaymentRequest is constructed using the supplied supportedMethods list, the payment details, the payment options, and any payment method specific data.

            ["visa", "bitcoin", "bobpay.com"]
          

            {
              "items": [
                {
                  "id": "basket",
                  "label": "Sub-total",
                  "amount": { "currency": "USD", "value" : "55.00" }, // US$55.00
                },
                {
                  "id": "tax",
                  "label": "Sales Tax",
                  "amount": { "currency": "USD", "value" : "5.00" }, // US$5.00
                },
                {
                  "id": "total",
                  "label": "Total due",
                  "amount": { "currency": "USD", "value" : "60.00" }, // US$60.00
                }
              ]
            }
          

            {
              "requestShipping": true
            }
          

            {
              "bobpay.com": {
                  "merchantIdentifier": "XXXX",
                  "bobPaySpecificField": true
              },
              "bitcoin": {
                  "address": "XXXX"
              }
            }
          

The PaymentRequest constructor MUST act as follows:

1. If the length of the supportedMethods sequence is zero, then throw a TypeError.
2. If the global object of the script calling the constructor is not considered a secure context, then throw a SecurityError.
   Using [SecureContext] in Web IDL will allow us to eliminate this prose.
3. If the browsing context of the script calling the constructor is not a top-level browsing context, then throw a SecurityError.

   There is an open issue about requiring a top-level browsing context for using PaymentRequest. Requiring one is a mitigation for a user being tricked into thinking a trusted site is asking for payment when in fact an untrusted iframe is asking for payment. The problem is some iframes may have a legitimate reason to request payment.

4. If details does not contain a sequence of items with length greater than zero, then throw a TypeError.
5. If data is not a JSON-serializable object, then throw a TypeError.
6. If the name of any top level field of data does not match one of the payment method identifiers in supportedMethods, then throw a TypeError.
7. If the value of any top level field is not a JSON-serializable object, then throw a TypeError.
8. Let request be a new PaymentRequest.
9. Store supportedMethods into request@[[\supportedMethods]].
10. Store details into request@[[\details]].
11. Store options into request@[[\options]].
12. Store data into request@[[\data]].
13. Set the value request@[[\state]] to created.
14. Set the value of the shippingAddress attribute on request to null.
15. Set the value of the shippingOption attribute on request to null.
16. If details contains a shippingOptions sequence with a length of 1, then set shippingOption to the id of the only ShippingOption in the sequence.
17. Set the value request@[[\updating]] to false.
18. Return request.

show()

The show method is called when the page wants to begin user interaction for the payment request. The show method will return a Promise that will be resolved when the user accepts the payment request. Some kind of user interface will be presented to the user to facilitate the payment request after the show method returns.

It may help users understand what they are accepting if the web site is able to label the "accept" button. For example, if a user is about to "Buy" something, "Reserve" something, "Subscribe" to something, etc. That said, this may create payment interface/experience issues and accidentally lead to customers thinking they're performing actions like a one-time purchase, when they are in fact signing up for a subscription.

The show method MUST act as follows:

1. Let request be the PaymentRequest object on which the method is called..
2. If the value of request@[[\state]] is not created then throw an InvalidStateError.
3. Set the value of request@[[\state]] to interactive.
4. Let acceptPromise be a new Promise.
5. Store acceptPromise in request@[[\acceptPromise]].
6. Return acceptPromise and asynchronously perform the remaining steps.
7. Let acceptedMethods be the sequence of payment method identifiers request@[[\supportedMethods]] with all identifiers removed that the user agent does not accept.
8. If the length of acceptedMethods is zero, then reject acceptPromise with a NotSupportedError.
9. 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.

abort()

The abort method may be called if the web page wishes to abort the payment request after the show method has been called and before the [[\acceptPromise]] has been resolved.

The abort method MUST act as follows:

1. If the value of [[\state]] is not interactive then throw an InvalidStateError.
2. Set the value of the internal slot [[\state]] to closed.
3. Return from the method and asynchronously perform the remaining steps.
4. Abort the current user interaction and close down any remaining user interface

State transitions

The internal slot [[\state]] follows the following state transitions:

shippingAddress

shippingAddress is populated when the user provides a shipping address. It is null by default. When a user provides a shipping address, the shipping address changed algorithm runs.

onshippingaddresschange is an EventHandler for an Event named shippingaddresschange.

shippingOption

shippingOption is populated when the user chooses a shipping option. It is null by default. When a user chooses a shipping option, the shipping option changed algorithm runs.

onshippingoptionchange is an EventHandler for an Event named shippingoptionchange.

Internal Slots

Instances of PaymentRequest are created with the internal slots in the following table:

complete()

The complete method must be called after the user has accepted the payment request and the [[\acceptPromise]] has been resolved. The complete method takes a boolean argument that indicates the payment was successfully processed if true and that processing failed if false. Calling the complete method tells the user agent that the user interaction is over (and should cause any remaining user interface to be closed).

The complete method MUST act as follows:

1. Let promise be a new Promise.
2. If the value of the internal slot [[\completeCalled]] is true, then throw an InvalidStateError.
3. Set the value of the internal slot [[\completeCalled]] to true.
4. Return promise and asynchronously perform the remaining steps.
5. Pass the value of success to the Payment App that accepted the payment request.
6. Close down any remaining user interface.
7. Resolve promise with undefined.

Internal Slots

Instances of PaymentResponse are created with the internal slots in the following table:

PaymentRequestUpdateEvent

[Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict)]
interface PaymentRequestUpdateEvent : Event {
  void updateWith(Promise<PaymentDetails> d);
};

dictionary PaymentRequestUpdateEventInit : EventInit {
};
        

The PaymentRequestUpdateEvent enables the web page to update the details of the payment request in response to a user interaction.

If the web page wishes to update the payment request then it should call updateWith and provide a promise that will resolve with a PaymentDetails dictionary containing changed values that the user agent SHOULD present to the user.

The PaymentRequestUpdateEvent constructor MUST set the internal slot [[\waitForUpdate]] to false.

The updateWith method MUST act as follows:

1. Let target be the PaymentRequest object that is the target of the event.
2. If the dispatch flag is unset, then throw an InvalidStateError.
3. If [[\waitForUpdate]] is true, then throw an InvalidStateError.
4. If target@[[\state]] is not interactive, then throw an InvalidStateError.
5. If target@[[\updating]] is true, then throw an InvalidStateError.
6. Set the stop propagation flag and stop immediate propagation flag.
7. Set [[\waitForUpdate]] to true.
8. Set target@[[\updating]] to true.
9. The user agent SHOULD disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the web page has made changes required by the change. The web page MUST settle the promise d to indicate that the payment request is valid again.

   The user agent SHOULD disable any part of the user interface that could cause another update event to be fired. Only one update may be processed at a time.

   We should consider adding a timeout mechanism so that if the page never resolves the promise within a reasonable amount of time then the user agent behaves as if the promise was rejected.
10. Return from the method and asynchronously perform the remaining steps.
11. Wait until d settles.
12. If d is resolved with details and details is a PaymentDetails dictionary, then:
    1. If details contains an items value, then copy this value to the items field of target@[[\details]].
    2. If details contains a shippingOptions sequence, then copy this value to the shippingOptions field of target@[[\details]].
    3. Let newOption be null.
    4. If details contains a shippingOptions sequence with a length of 1, then set newOption to the id of the only ShippingOption in the sequence.
    5. Set the value of shippingOption on target to newOption.
13. Set [[\waitForUpdate]] to false.
14. Set target@[[\updating]] to false.
15. The user agent should update the user interface based on any changed values in target. The user agent SHOULD re-enable user interface elements that might have been disabled in the steps above if appropriate.

Shipping address changed algorithm

The shipping address changed algorithm runs when the user provides a new shipping address. It MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let name be shippingaddresschange.
3. Set the shippingAddress attribute on request to the shipping address provided by the user.
4. Run the PaymentRequest updated algorithm with request and name.

Shipping option changed algorithm

The shipping option changed algorithm runs when the user chooses a new shipping option. It MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let name be shippingoptionchange.
3. Set the shippingOption attribute on request to the id string of the ShippingOption provided by the user.
4. Run the PaymentRequest updated algorithm with request and name.

PaymentRequest updated algorithm

The PaymentRequest updated algorithm is run by other algorithms above to fire an event to indicate that a user has made a change to a PaymentRequest called request with an event name of name.

It MUST run the following steps:

1. If the request@[[\updating]] is true, then terminate this algorithm and take no further action. Only one update may take place at a time. This should never occur.
2. If the request@[[\state]] is not set to interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. Let event be a new PaymentRequestUpdateEvent.
4. Queue a task to fire an event named name of type event at request.

User agent delegates payment request algorithm

The PaymentRequest interface allows a web page to call abort to tell the user agent to abort the payment request and to tear down any user interface that might be shown. For example, a web page may choose to do this the goods they are selling are only available for a limited amount of time. If the user does not accept the payment request within the allowed time period, then the request will be aborted.

A user agent may not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. To support this situation, the user agent must run the User agent delegates payment request algorithm. The algorithm MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. If the request@[[\updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. If the request@[[\state]] is not interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
4. Set request@[[\state]] to delegated.

The architecture document suggests that payment apps may take numerous forms, including as web-based apps. This specification should describe how the user-agent will pass the payment request data and the complete signal to a web-based payment app and also how it will receive the payment response from the payment app.

This specification should describe how the user agent will pass the payment request data and the complete signal to a native payment app and also how it will receive the payment response from the payment app.

User accepts the payment request algorithm

The user accepts the payment request algorithm runs when the user accepts the payment request and confirms that they want to pay. It MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. If the request@[[\updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. If request@[[\state]] is not interactive and the not delegated, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
4. 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.
5. Let response be a new PaymentResponse.
6. Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
7. Set the details attribute value of response to a JSON-serializable object containing the payment method specific message used by the merchant to process the transaction. The format of this response will be defined by a Payment Transaction Message Specification.
8. Set response@[[\completeCalled]] to false.
9. Set request@[[\state]] to closed.
10. Resolve the pending promise request@[[\acceptPromise]].