Payment Request API

W3C Candidate Recommendation

This version:
https://www.w3.org/TR/2018/CR-payment-request-20180222/
Latest published version:
https://www.w3.org/TR/payment-request/
Latest editor's draft:
https://w3c.github.io/payment-request/
Test suite:
https://w3c-test.org/payment-request/
Implementation report:
https://w3c.github.io/payment-request/reports/implementation.html
Previous version:
https://www.w3.org/TR/2018/CR-payment-request-20180123/
Editors:
Adrian Bateman, Microsoft Corporation
Zach Koch, Google
Roy McElmurry, Facebook
Domenic Denicola, Google
Marcos Cáceres, Mozilla
Participate:
GitHub w3c/payment-request
File a bug
Commit history
Pull requests
Can I use this API?:
caniuse.com

Copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Abstract

This specification standardizes an API to allow merchants (i.e. web sites selling physical or digital goods) to utilize one or more payment methods with minimal integration. User agents (e.g., browsers) facilitate the payment flow between merchant and user.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The working group maintains a list of all bug reports that the group has not yet addressed. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

The deadline for comments for Candidate Recommendation is 31 October 2017.

Note: Sending comments on this document

If you wish to make comments regarding this document, please raise them as GitHub issues. Only send comments by email if you are unable to raise issues on GitHub (see links below). All comments are welcome.

The working group will demonstrate implementation experience by producing an implementation report. The report will show two or more independent implementations passing each mandatory test in the test suite (i.e., each test corresponds to a MUST requirement of the specification).

There has been no change in dependencies on other workings groups during the development of this specification.

This document was published by the Web Payments Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 31 October 2017.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

Features at risk

As this specification enters the Candidate Recommendation phase of the W3C standardization process, the working group has identified the following feature(s) as being "at risk" of being removed from the specification. The working group seeks input from implementers, developers, and the general public on whether these features should remain in the specification. If no compelling use cases are received, or if there is limited interest from implementers, these features will be removed from the specification before proceeding along the W3C Recommendation track.

1. Introduction

This section is non-normative.

This specification describes an API that allows user agents (e.g., browsers) to act as an intermediary between three parties in a transaction:

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

This API also enables web sites to take advantage of more secure payment schemes (e.g., tokenization and system-level authentication) that are not possible with standard JavaScript libraries. This has the potential to reduce liability for the merchant and helps protect sensitive user information.

1.1 Goals

1.1.1 Out of scope

  • Create a new payment method
  • Integrate directly with payment processors

2. Examples of usage

This section is non-normative.

In order to use the API, the developer needs to provide and keep track of a number of key pieces of information. These bits of information are passed to the PaymentRequest constructor as arguments, and subsequently used to update the payment request being displayed to the user. Namely, these bits of information are:

Once a PaymentRequest is constructed, it's presented to the end user via the show() method. The show() returns a promise that, once the user confirms request for payment, results in a PaymentResponse.

2.1 The methodData argument

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 data.

Example 1: The `methodData` argument
const methodData = [
  {
    supportedMethods: "basic-card",
    data: {
      supportedNetworks: ["visa", "mastercard"],
      supportedTypes: ["debit", "credit"],
    },
  },
  {
    supportedMethods: "https://example.com/bobpay",
    data: {
      merchantIdentifier: "XXXX",
      bobPaySpecificField: true,
    },
  },
];

2.2 The details argument

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

Example 2: The `details` argument
const details = {
  id: "super-store-order-123-12312",
  displayItems: [
    {
      label: "Sub-total",
      amount: { currency: "USD", value: "55.00" },
    },
    {
      label: "Sales Tax",
      amount: { currency: "USD", value: "5.00" },
      type: "tax"
    },
  ],
  total: {
    label: "Total due",
    // The total is USD$65.00 here because we need to
    // add shipping (below). The selected shipping
    // costs USD$5.00.  
    amount: { currency: "USD", value: "65.00" },
  },
};

2.2.1 Shipping options

Here we see an example of how to add two shipping options to the details.

Example 3: Adding shipping options
const shippingOptions = [
  {
    id: "standard",
    label: "🚛 Ground Shipping (2 days)",
    amount: { currency: "USD", value: "5.00" },
    selected: true,
  },
  {
    id: "drone",
    label: "🚀 Drone Express (2 hours)",
    amount: { currency: "USD", value: "25.00" }
  },
];
Object.assign(details, { shippingOptions });

2.2.2 Conditional modifications to payment request

Here we see how to add a processing fee for using a credit card. Notice that it requires recalculating the total.

Example 4: Modifying payment request based on card type
// Credit card incurs a $3.00 processing fee.
const creditCardFee = {
  label: "Credit card processing fee",
  amount: { currency: "USD", value: "3.00" },
};

// Modifiers apply when the user chooses to pay with
// a credit card.
const modifiers = [
  {
    additionalDisplayItems: [creditCardFee],
    supportedMethods: "basic-card",
    total: {
      label: "Total due",
      amount: { currency: "USD", value: "68.00" },
    },
    data: {
      supportedTypes: "credit",
    },
  },
];
Object.assign(details, { modifiers });

2.3 The options argument

The options dictionary contains information the developer needs from the user to perform the payment (e.g., the payer's name and shipping address).

Example 5: The `options` argument
const options = {
  requestPayerEmail: false,
  requestPayerName: true,
  requestPayerPhone: false,
  requestShipping: true,
}

2.4 Constructing a PaymentRequest

Having gathered all the prerequisite bits of information, we can now construct a PaymentRequest and request that the browser present it to the user:

Example 6: Constructing a `PaymentRequest`
async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    // See below for a detailed example of handling these events
    request.onshippingaddresschange = ev => ev.updateWith(details);
    request.onshippingoptionchange = ev => ev.updateWith(details);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}
async function validateResponse(response) {
  try {
    if (await checkAllValuesAreGood(response)) {
      await response.complete("success");
    } else {
      await response.complete("fail");
    }
  } catch (err) {
    // Something went wrong...
    await response.complete("fail");
  }
}
doPaymentRequest();

2.5 Handling events and updating the payment request

Prior to the user accepting to make payment, the site is given an opportunity to update the payment request in response to user input. This can include, for example, providing additional shipping options (or modifying their cost), removing items that cannot ship to a particular address, etc.

Example 7: Registering event handlers
const request = new PaymentRequest(methodData, details, options);
// Async update to details
request.onshippingaddresschange = ev => {
  ev.updateWith(checkShipping(request));
};
// Sync update to the total
request.onshippingoptionchange = ev => {
  const shippingOption = shippingOptions.find(
    option => option.id === request.id
  );
  const newTotal = {
    currency: "USD",
    label: "Total due",
    value: calculateNewTotal(shippingOption),
  };
  ev.updateWith({ ...details, total: newTotal });
};
async function checkShipping(request) {
  try {
    const json = request.shippingAddress.toJSON();

    await ensureCanShipTo(json);
    const { shippingOptions, total } = await calculateShipping(json);

    return { ...details, shippingOptions, total };
  } catch (err) {
    return { ...details, error: `Sorry! we can't ship to your address.` };
  }
}

2.6 POSTing payment response back to a server

It's expected that data in a PaymentResponse will be POSTed back to a server for processing. To make this as easy as possible, PaymentResponse provides a toJSON() method that serializes the object directly into JSON. This makes it trivial to POST the resulting JSON back to a server using the Fetch API:

Example 8: POSTing with `fetch()`
async function doPaymentRequest() {
  const payRequest = new PaymentRequest(methodData, details, options);
  const payResponse = await payRequest.show();
  let result = "";
  try {
    const httpResponse = await fetch("/process-payment", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: payResponse.toJSON(),
    });
    result = httpResponse.ok ? "success" : "fail";
  } catch (err) {
    console.error(err);
    result = "fail";
  }
  await payResponse.complete(result);
}
doPaymentRequest();

3. PaymentRequest interface 

[Constructor(sequence<PaymentMethodData> methodData, PaymentDetailsInit details, optional PaymentOptions options),
 SecureContext,
 Exposed=Window]
interface PaymentRequest : EventTarget {
    Promise<PaymentResponse> show();
    Promise<void>            abort();
    Promise<boolean>         canMakePayment();

    readonly attribute DOMString            id;
    readonly attribute PaymentAddress?      shippingAddress;
    readonly attribute DOMString?           shippingOption;
    readonly attribute PaymentShippingType? shippingType;

             attribute EventHandler         onshippingaddresschange;

             attribute EventHandler         onshippingoptionchange;
};
Note

A developer creates a PaymentRequest to make a payment request. This is typically associated with the user initiating a payment process (e.g., by activating a "Buy," "Purchase," or "Checkout" button on a web site, selecting a "Power Up" in an interactive game, or paying at a kiosk in a parking structure). The PaymentRequest allows developers to exchange information with the user agent while the user is providing input (up to the point of user approval or denial of the payment request).

The shippingAddress, shippingOption, and shippingType attributes are populated during processing if the requestShipping member is set.

Because the simultaneous display of multiple PaymentRequest user interfaces might confuse the user, this specification limits the user agent to displaying one at a time via the show() method. This is ensured by a payment request is showing boolean.

3.1 Constructor

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

The PaymentRequest(methodData, details, options) constructor MUST act as follows:

  1. If the current settings object's responsible document is not allowed to use the feature indicated by attribute name allowpaymentrequest, then throw a "SecurityError" DOMException.
  2. Let serializedMethodData be an empty list.
  3. Establish the request's id:
    1. If details.id is missing, add an id member to details and set its value to a UUID [RFC4122].
  4. Process payment methods:
    1. If the length of the methodData sequence is zero, then throw a TypeError, optionally informing the developer that at least one payment method is required.
    2. For each paymentMethod of methodData:
      1. Run the steps to validate a payment method identifier with paymentMethod.supportedMethods. If it returns false, then throw a RangeError exception and terminate this algorithm. Optionally, inform the developer that the payment method identifier is invalid.
      2. If the data member of paymentMethod is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing paymentMethod.data into a string. Rethrow any exceptions.
      3. Add the tuple (paymentMethod.supportedMethods, serializedData) to serializedMethodData.
  5. Process the total:
    1. Check and canonicalize total details.total.amount. Rethrow any exceptions.
  6. If the displayItems member of details is present, then for each item in details.displayItems:
    1. Check and canonicalize amount item.amount. Rethrow any exceptions.
  7. Let selectedShippingOption be null.
  8. If the requestShipping member of options is present and set to true, process shipping options:
    1. Let options be an empty sequence<PaymentShippingOption>.
    2. If the shippingOptions member of details is present, then:
      1. Let seenIDs be an empty list.
      2. Set options to details.shippingOptions.
      3. For each option in options:
        1. Check and canonicalize amount item.amount. Rethrow any exceptions.
        2. If seenIDs contains option.id, then throw a TypeError. Optionally, inform the developer that shipping option IDs must be unique.
        3. Otherwise, append option.id to seenIDs.
      4. For each option in options:
        1. If option.selected is true, then set selectedShippingOption to option.id.
    3. Set details.shippingOptions to options.
  9. Let serializedModifierData be an empty list.
  10. Process payment details modifiers:
    1. Let modifiers be an empty sequence<PaymentDetailsModifier>.
    2. If the modifiers member of details is present, then:
      1. Set modifiers to details.modifiers.
      2. For each modifier of modifiers:
        1. If the total member of modifier is present, then:
          1. Check and canonicalize total modifier.total.amount. Rethrow any exceptions.
        2. If the additionalDisplayItems member of modifier is present, then for each item of modifier.additionalDisplayItems:
          1. Check and canonicalize amount item.amount. Rethrow any exceptions.
        3. If the data member of modifier is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing modifier.data into a string. Rethrow any exceptions.
        4. Add serializedData to serializedModifierData.
        5. Remove the data member of modifier, if it is present.
    3. Set details.modifiers to modifiers.
  11. Let request be a new PaymentRequest.
  12. Set request.[[options]] to options.
  13. Set request.[[state]] to "created".
  14. Set request.[[updating]] to false.
  15. Set request.[[details]] to details.
  16. Set request.[[serializedModifierData]] to serializedModifierData.
  17. Set request.[[serializedMethodData]] to serializedMethodData.
  18. Set the value of request's shippingOption attribute to selectedShippingOption.
  19. Set the value of the shippingAddress attribute on request to null.
  20. If options.requestShipping is set to true, then set the value of the shippingType attribute on request to options.shippingType. Otherwise, set it to null.
  21. Return request.

3.2 id attribute

When getting, the id attribute returns this PaymentRequest's [[details]].id.

3.3 show() method

Note

The show() method is called when a developer wants to begin user interaction for the payment request. The show() method returns 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 is not possible to show multiple PaymentRequests at the same time within one user agent. If a PaymentRequest is already showing, calling show() —from any Web site— will return a promise rejected with an "AbortError" DOMException.

The show() method MUST act as follows:

  1. Let request be the PaymentRequest object on which the method is called.
  2. Let document be request's relevant global object's associated Document.
  3. If document is not fully active, then return a promise rejected with an "AbortError" DOMException.

  4. Optionally, if the user agent wishes to disallow the call to show() to protect the user, then return a promise rejected with a "SecurityError" DOMException. For example, the user agent may require the call to be triggered by user activation, or may limit the rate at which a page can call show().

    Note

    During the Candidate Recommendation phase, implementations are expected to experiment in this area. Developers using this API should investigate and anticipate such experiments and understand under what circumstances a "SecurityError" DOMException might occur. If interoperable behavior emerges amongst user agents, then that behavior will be standardized here before progressing the specification along the W3C Recommendation Track.

  5. If request.[[state]] is not "created" then return a promise rejected with an "InvalidStateError" DOMException.
  6. If the user agent's payment request is showing boolean is true, then return a promise rejected with an "AbortError" DOMException.
  7. Set request.[[state]] to "interactive".
  8. Let acceptPromise be a new Promise.
  9. Set request.[[acceptPromise]] to acceptPromise.

  10. Optionally:

    1. Reject acceptPromise with an "AbortError" DOMException.
    2. Set request.[[state]] to "closed".
    3. Return acceptPromise.
    Note

    This allows the user agent to act as if the user had immediately aborted the payment request, at its discretion. For example, in "private browsing" modes or similar, user agents might take advantage of this step.

  11. Set the user agent's payment request is showing boolean to true.
  12. Return acceptPromise and perform the remaining steps in parallel.
  13. Let handlers be an empty unordered set.
  14. For each paymentMethod tuple in request.[[serializedMethodData]]:
    1. Let identifier be the first element in the paymentMethod tuple.
    2. Let data be the result of JSON-parsing the second element in the paymentMethod tuple.
    3. If required by the specification that defines the identifer, then convert data to an IDL value. Otherwise, convert to object.
    4. If conversion results in an error, reject acceptPromise with that error and terminate this algorithm.
    5. If the user agent has a registered payment handler that supports identifier, then check if the payment handler is authorized and capable of handling the payment request with data. If the check returns in the affirmative, then add payment handler to handlers.
  15. If handlers is empty, then reject acceptPromise with a "NotSupportedError" DOMException, and set the user agent's payment request is showing boolean to false.

  16. Otherwise, present a user interface to allow the user to interact with the handlers. The user agent SHOULD prioritize the preference of the user when presenting payment methods. It is RECOMMENDED that the language of the user interface match the language of the body element.

    For the payment handler selected by the end-user, the user agent MUST pass the converted second element in the paymentMethod tuple. Optionally, the user agent SHOULD send the appropriate data from request to the user-selected payment handler in order to guide the user through the payment process. This includes the various attributes and internal slots of request (some MAY be excluded for privacy reasons where appropriate).

    The acceptPromise will later be resolved or rejected by either the user accepts the payment request algorithm or the user aborts the payment request algorithm, which are triggered through interaction with the user interface.

    If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then the user interface SHOULD be hidden, and acceptPromise SHOULD be rejected with an "AbortError" DOMException.

3.4 abort() method

Note

The abort() method is called if a developer wishes to tell the user agent to abort the payment request and to tear down any user interface that might be shown. The abort() can only be called after the show() method has been called (see states) and before this instance's [[acceptPromise]] has been resolved. For example, developers might choose to do this if 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 might not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. In this situation, abort() will reject the returned Promise.

See also the algorithm when the user aborts the payment request.

The abort() 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 "interactive" then throw an "InvalidStateError" DOMException.
  3. Let promise be a new Promise.
  4. Return promise and perform the remaining steps in parallel.
  5. Try to abort the current user interaction with the payment handler and close down any remaining user interface.
  6. Queue a task on the user interaction task source to perform the following steps:
    1. If it is not possible to abort the current user interaction, then reject promise with "InvalidStateError" DOMException and abort these steps.
    2. Set the value of the internal slot request.[[state]] to "closed".
    3. Reject the promise request.[[acceptPromise]] with an "AbortError" DOMException.
    4. Resolve promise with undefined.

3.5 canMakePayment() method

Note

The canMakePayment() method can be used by the developer to determine if the PaymentRequest object can be used to make a payment, before they call show(). It returns a Promise that will be fulfilled with true if the user agent supports any of the desired payment methods supplied to the PaymentRequest constructor, and false if none are supported. If the method is called too often, the user agent might instead return a promise rejected with a "NotAllowedError" DOMException, at its discretion.

The canMakePayment() method MUST act as follows:

  1. Let request be the PaymentRequest object on which the method was called.
  2. If request.[[state]] is not "created", then return a promise rejected with an "InvalidStateError" DOMException.
  3. Optionally, at the user agent's discretion, return a promise rejected with a "NotAllowedError" DOMException.
    Note

    This allows user agents to apply heuristics to detect and prevent abuse of the canMakePayment() method for fingerprinting purposes, such as creating PaymentRequest objects with a variety of supported payment methods and calling canMakePayment() on them one after the other. For example, a user agent may restrict the number of successful calls that can be made based on the top-level browsing context or the time period in which those calls were made.

  4. Let promise be a new Promise.
  5. Return promise, and perform the remaining steps in parallel.
  6. For each methodData in request.[[serializedMethodData]]:
    1. If methodData.supportedMethods is a supported payment method identifier (including its payment method specific capabilities), resolve promise with true, and abort this algorithm.
  7. Resolve promise with false.

3.6 shippingAddress attribute

A PaymentRequest's shippingAddress attribute 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.

3.7 shippingType attribute

A PaymentRequest's shippingType attribute is the type of shipping used to fulfill the transaction. Its value is either a PaymentShippingType enum value, or null if none is provided by the developer during construction (see PaymentOptions's shippingType member).

3.8 onshippingaddresschange attribute

A PaymentRequest's onshippingaddresschange attribute is an EventHandler for a PaymentRequestUpdateEvent named shippingaddresschange.

3.9 shippingOption attribute

A PaymentRequest's shippingOption attribute 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.

3.10 onshippingoptionchange attribute

A PaymentRequest's onshippingoptionchange attribute is an EventHandler for a PaymentRequestUpdateEvent named shippingoptionchange.

3.11 Internal Slots

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

Internal Slot Description (non-normative)
[[serializedMethodData]] 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).
[[serializedModifierData]] A list containing the serialized string form of each data member for each corresponding item in the sequence [[details]].modifier, or null if no such member was present.
[[details]] The current PaymentDetailsBase for the payment request initially supplied to the constructor and then updated with calls to updateWith(). Note that all data members of PaymentDetailsModifier instances contained in the modifiers member will be removed, as they are instead stored in serialized form in the [[serializedModifierData]] internal slot.
[[options]] The PaymentOptions supplied to the constructor.
[[state]]

The current state of the payment request, which transitions from:

"created"
The payment request is constructed and has not been presented to the user.
"interactive"
The payment request is being presented to the user.
"closed"
The payment request completed.

The state transitions are illustrated in the figure below:

Figure 1 The constructor sets the initial state to "created". The show() method changes the state to "interactive". From there, the abort() method or any other error can send the state to "closed"; similarly, the user accepts the payment request algorithm and user aborts the payment request algorithm will change the state to "closed".
[[updating]] true is there is a pending updateWith() call to update the payment request and false otherwise.
[[acceptPromise]] The pending Promise created during show that will be resolved if the user accepts the payment request.

4. PaymentMethodData dictionary 

dictionary PaymentMethodData {
    required DOMString supportedMethods;
             object    data;
};

A PaymentMethodData dictionary is used to indicate a set of supported payment methods and any associated payment method specific data for those methods.

supportedMethods member
A payment method identifier for a payment method that the merchant web site accepts.
data member
An object that provides optional information that might be needed by the supported payment methods. If supplied, it will be JSON-serialized.
Note

The value of supportedMethods was changed from array to string, but the name was left as a plural to maintain compatibility with existing content on the Web.

5. PaymentCurrencyAmount dictionary 

dictionary PaymentCurrencyAmount {
    required DOMString currency;
    required DOMString value;
    // Note: currencySystem is "at risk" of being removed!
             DOMString currencySystem = "urn:iso:std:iso:4217";
};

A PaymentCurrencyAmount dictionary is used to supply monetary amounts.

Feature at Risk

This feature has been marked "at risk". If you'd like for this feature to remain in the specification, please describe your use case in issue 490.

currencySystem member
A URL that indicates the currency system that the currency identifier belongs to. By default, the value is "urn:iso:std:iso:4217" indicating that currency is defined by [ISO4217] (for example, USD for US Dollars).
currency member

A string containing a currency identifier. The value of currency can be any string that is valid within the currency system indicated by currencySystem.

When using [ISO4217], all well-formed 3-letter alphabetic codes are allowed (i.e., the numeric codes are not supported). Their canonical form is upper case. However, the set of combinations of currency code for which localized currency symbols are available is implementation dependent. Where a localized currency symbol is not available, a user agent SHOULD use U+00A4 (¤) for formatting. User agents MAY format the display of the currency member to adhere to OS conventions (e.g., for localization purposes).

value member
A valid decimal monetary value containing a monetary amount.

The following example shows how to represent US$55.00.

Example 9
{
  "currency": "USD",
  "value" : "55.00"
}

5.1 Validity checkers

A JavaScript string is a valid decimal monetary value if it consists of the following code points in the given order: [INFRA]

  1. Optionally, a single U+002D (-), to indicate that the amount is negative.
  2. One or more code points in the range U+0030 (0) to U+0039 (9).
  3. Optionally, a single U+002E (.) followed by one or more code points in the range U+0030 (0) to U+0039 (9).
Note
The following regular expression is an implementation of the above definition. 
^-?[0-9]+(\.[0-9]+)?$

To check and canonicalize amount given a PaymentCurrencyAmount amount, run the following steps:

  1. If amount.currencySystem is not "urn:iso:std:iso:4217", terminate this algorithm.
  2. Let isValidCurrency be the result of calling IsWellFormedCurrencyCode abstract operation with amount.currency as the argument.
  3. If isValidCurrency is false, then throw a RangeError exception and terminate this algorithm, optionally informing the developer that the currency is invalid.
  4. If amount.value is not a valid decimal monetary value, throw a TypeError, optionally informing the developer that the currency is invalid.
  5. Set amount.currency to the result of ASCII uppercasing amount.currency.

To check and canonicalize total given a PaymentCurrencyAmount total, run the following steps:

  1. If total.currencySystem is not "urn:iso:std:iso:4217", terminate this algorithm.
  2. Check and canonicalize amount amount. Rethrow any exceptions.
  3. If the first code point of value is U+002D (-), then throw a TypeError optionally informing the developer that a total can't be a negative number.
Note: No alteration of values

6. Payment details dictionaries

6.1 PaymentDetailsBase dictionary 

dictionary PaymentDetailsBase {
    sequence<PaymentItem>            displayItems;
    sequence<PaymentShippingOption>  shippingOptions;
    sequence<PaymentDetailsModifier> modifiers;
};
displayItems member
A sequence of PaymentItem dictionaries contains line items for the payment request that the user agent MAY display.
Note
shippingOptions member

A sequence containing the different shipping options for the user to choose from.

If an item in the sequence has the selected member set to true, then this is the shipping option that will be used by default and shippingOption will be set to the id of this option without running the shipping option changed algorithm. If more than one item in the sequence has selected set to true, then the user agent selects the last one in the sequence.

The shippingOptions member is only used if the PaymentRequest was constructed with PaymentOptions requestShipping set to true.

Note
modifiers member
A sequence of PaymentDetailsModifier dictionaries that contains modifiers for particular payment method identifiers. For example, it allows you to adjust the total amount based on payment method.

6.2 PaymentDetailsInit dictionary 

dictionary PaymentDetailsInit : PaymentDetailsBase {
             DOMString   id;
    required PaymentItem total;
};
Note

In addition to the members inherited from the PaymentDetailsBase dictionary, the following members are part of the PaymentDetailsInit dictionary:

id member
A free-form identifier for this payment request.
Note
total member
A PaymentItem containing a non-negative total amount for the payment request.
Note

6.3 PaymentDetailsUpdate dictionary 

dictionary PaymentDetailsUpdate : PaymentDetailsBase {
    DOMString   error;
    PaymentItem total;
};

The PaymentDetailsUpdate dictionary is used to update the payment request using updateWith().

In addition to the members inherited from the PaymentDetailsBase dictionary, the following members are part of the PaymentDetailsUpdate dictionary:

error member
A human-readable string. When the payment request is updated using updateWith(), the PaymentDetailsUpdate can contain a message in the error member that will be displayed to the user, if the PaymentDetailsUpdate indicates that there are no valid shippingOptions (and the PaymentRequest was constructed with the requestShipping option set to true). This can be used to explain why goods cannot be shipped to the chosen shipping address, or any other reason why no shipping options are available.
total member
A PaymentItem contains the non-negative amount.
Note

Algorithms in this specification that accept a PaymentDetailsUpdate dictionary will throw if the total.amount.value is a negative number.

7. PaymentDetailsModifier dictionary 

dictionary PaymentDetailsModifier {
    required DOMString             supportedMethods;
             PaymentItem           total;
             sequence<PaymentItem> additionalDisplayItems;
             object                data;
};

The PaymentDetailsModifier dictionary provides details that modify the PaymentDetailsBase based on a payment method identifier. It contains the following members:

supportedMethods member
A payment method identifier. The members of the PaymentDetailsModifier only apply if the user selects this payment method.
total member
A PaymentItem value that overrides the total member in the PaymentDetailsInit dictionary for the payment method identifiers of the supportedMethods member.
additionalDisplayItems member
A sequence of PaymentItem dictionaries provides additional display items that are appended to the displayItems member in the PaymentDetailsBase dictionary for the payment method identifiers in the supportedMethods member. This member is commonly used to add a discount or surcharge line item indicating the reason for the different total amount for the selected payment method that the user agent MAY display.
Note

It is the developer's responsibility to verify that the total amount is the sum of the displayItems and the additionalDisplayItems.

data member
An object that provides optional information that might be needed by the supported payment methods. If supplied, it will be JSON-serialized.

8. PaymentShippingType enum 

enum PaymentShippingType {
    "shipping",
    "delivery",
    "pickup"
};
"shipping"
This is the default and refers to the address being collected as the destination for shipping.
"delivery"
This refers to the address being collected as being used for delivery. This is commonly faster than shipping. For example, it might be used for food delivery.
"pickup"
This refers to the address being collected as part of a service pickup. For example, this could be the address for laundry pickup.

9. PaymentOptions dictionary 

dictionary PaymentOptions {
    boolean             requestPayerName = false;
    boolean             requestPayerEmail = false;
    boolean             requestPayerPhone = false;
    boolean             requestShipping = false;
    PaymentShippingType shippingType = "shipping";
};
Note

The PaymentOptions dictionary is passed to the PaymentRequest constructor and provides information about the options desired for the payment request.

requestPayerName member
A boolean that indicates whether the user agent SHOULD collect and return the payer's name as part of the payment request. For example, this would be set to true to allow a merchant to make a booking in the payer's name.
requestPayerEmail member
A boolean that indicates whether the user agent SHOULD collect and return the payer's email address as part of the payment request. For example, this would be set to true to allow a merchant to email a receipt.
requestPayerPhone member
A boolean that indicates whether the user agent SHOULD collect and return the payer's phone number as part of the payment request. For example, this would be set to true to allow a merchant to phone a customer with a billing enquiry.
requestShipping member
A boolean that indicates whether the user agent SHOULD collect and return a shipping address as part of the payment request. For example, this would be set to true when physical goods need to be shipped by the merchant to the user. This would be set to false for the purchase of digital goods.
shippingType member
A ShippingType enum value. Some transactions require an address for delivery but the term "shipping" isn't appropriate. For example, "pizza delivery" not "pizza shipping" and "laundry pickup" not "laundry shipping". If requestShipping is set to true, then the shippingType member can influence the way the user agent presents the user interface for gathering the shipping address.

The shippingType member only affects the user interface for the payment request.

10. PaymentItem dictionary 

dictionary PaymentItem {
    required DOMString             label;
    required PaymentCurrencyAmount amount;
             boolean               pending = false;
    // Note: type member is "at risk" of being removed!
             PaymentItemType       type;
};

A sequence of one or more PaymentItem dictionaries is included in the PaymentDetailsBase dictionary to indicate what the payment request is for and the value asked for.

label member
A human-readable description of the item. The user agent may display this to the user.
amount member
A PaymentCurrencyAmount containing the monetary amount for the item.
pending member
A boolean. When set to true it means that the amount member is not final. This is commonly used to show items such as shipping or tax amounts that depend upon selection of shipping address or shipping option. User agents MAY indicate pending fields in the user interface for the payment request.
Feature at Risk

This feature has been marked "at risk". Firefox plans to experiment with this feature during the Candidate Recommendation phase. If you'd like for this feature to remain in the specification, please signal your support for it to remain in issue 163.

type member
A PaymentItemType enum value, which a developer can use to explicitly indicate that this member is of a particular type. A user agent MAY use the value of type to assist in the presentation of PaymentItem by, for example, visually grouping types together or other otherwise distinguishing them from other types (or from items that have no associated type).
Feature at Risk

This feature has been marked "at risk". Firefox plans to experiment with this feature during the Candidate Recommendation phase. If you'd like for this feature to remain in the specification, please signal your support for it to remain in issue 163.

PaymentItemType enum 

enum PaymentItemType {
    "tax"
};

The PaymentItemType serves to categorize a PaymentItem into particular types.

"tax"
Indicates that the corresponding PaymentItem represents a form of taxation. Examples include sales tax, goods and services tax, value added tax, an so on.

11. PaymentAddress interface 

[SecureContext,
 Exposed=Window]
interface PaymentAddress {
    [Default] object toJSON();
    readonly attribute DOMString              country;
    readonly attribute FrozenArray<DOMString> addressLine;
    readonly attribute DOMString              region;
    readonly attribute DOMString              city;
    readonly attribute DOMString              dependentLocality;
    readonly attribute DOMString              postalCode;
    readonly attribute DOMString              sortingCode;
    readonly attribute DOMString              languageCode;
    readonly attribute DOMString              organization;
    readonly attribute DOMString              recipient;
    readonly attribute DOMString              phone;
};

11.1 Creating a PaymentAddress

The steps to create a payment address from user-provided input are given by the following algorithm.

  1. Let address be a new instance of PaymentAddress.
  2. Set address.[[addressLine]] to the result of splitting the user-provided address line into a frozen array. If none was provided, set it to the empty frozen array.
    Note
  3. Set address.[[country]] to the user-provided country as an upper case [ISO3166] alpha-2 code, or to the empty string if none was provided.
  4. Set the address.[[phone]] to the user-provided phone number for this shipping address, optionally formatted to adhere to [E.164], or to the empty string if none was provided.
    Note: Privacy of phone number
  5. Set address.[[languageCode]] to a canonicalized language tag, or to the empty string if none was provided.
    Issue 608: Describe how to implement PaymentAddress.languageCode
  6. Set address.[[city]] to the user-provided city, or to the empty string if none was provided.
  7. Set address.[[dependentLocality]] to the user-provided dependent locality, or to the empty string if none was provided.
  8. Set address.[[organization]] to the user-provided recipient organization, or to the empty string if none was provided.
  9. Set address.[[postalCode]] to the user-provided postal code, or to the empty string if none was provided.
  10. Set address.[[recipient]] to the user-provided recipient of the transaction, or to the empty string if none was provided.
  11. Set address.[[region]] to the user-provided region, or to the empty string if none was provided.
  12. Set address.[[sortingCode]] to the user-provided sorting code, or to the empty string if none was provided.
  13. Return address.

11.2 toJSON() method

When called, runs [WEBIDL]'s default toJSON operation.

11.3 country attribute

When getting, returns the value of the PaymentAddress's [[country]] internal slot.

11.4 addressLine attribute

When getting, returns the value of the PaymentAddress's [[addressLine]] internal slot.

11.5 region attribute

When getting, returns the value of the PaymentAddress's [[region]] internal slot.

11.6 city attribute

When getting, returns the value of the PaymentAddress's [[city]] internal slot.

11.7 dependentLocality attribute

When getting, returns the value of the PaymentAddress's [[dependentLocality]] internal slot.

11.8 postalCode attribute

When getting, returns the value of the PaymentAddress's [[postalCode]] internal slot.

11.9 sortingCode attribute

When getting, returns the value of the PaymentAddress's [[sortingCode]] internal slot.

11.10 languageCode attribute

When getting, returns the value of the PaymentAddress's [[languageCode]] internal slot.

11.11 organization attribute

When getting, returns the value of the PaymentAddress's [[organization]] internal slot.

11.12 recipient attribute

When getting, returns the value of the PaymentAddress's [[recipient]] internal slot.

11.13 phone attribute

When getting, returns the value of the PaymentAddress's [[phone]] internal slot.

11.14 Internal slots

Internal slot Description (non-normative)
[[country]] An [ISO3166] alpha-2 code. The canonical form is upper case. For example, "JP".
[[addressLine]] The most specific part of the address. It can include, for example, a street name, a house number, apartment number, a rural delivery route, descriptive instructions, or a post office box number.
[[region]] The top level administrative subdivision of the country. For example, this can be a state, a province, an oblast, or a prefecture.
[[city]] The city/town portion of the address.
[[dependentLocality]] The dependent locality or sublocality within a city. For example, used for neighborhoods, boroughs, districts, or UK dependent localities.
[[postalCode]] The postal code or ZIP code, also known as PIN code in India.
[[sortingCode]] The sorting code as used in, for example, France.
[[languageCode]] The [BCP47] language tag for the address, in canonical form. It's used to determine the field separators and the order of fields when formatting the address for display.
[[organization]] The organization, firm, company, or institution at this address.
[[recipient]] The name of the recipient or contact person. This member may, under certain circumstances, contain multiline information. For example, it might contain "care of" information.
[[phone]] The phone number of the recipient or contact person.

12. PaymentShippingOption dictionary 

dictionary PaymentShippingOption {
    required DOMString             id;
    required DOMString             label;
    required PaymentCurrencyAmount amount;
             boolean               selected = false;
};

The PaymentShippingOption dictionary has members describing a shipping option. Developers can provide the user with one or more shipping options by calling the updateWith() method in response to a change event.

id member
A string identifier used to reference this PaymentShippingOption. It MUST be unique for a given PaymentRequest.
label member
A human-readable string description of the item. The user agent SHOULD use this string to display the shipping option to the user.
amount member
A PaymentCurrencyAmount containing the monetary amount for the item.
selected member
A boolean. When true, it indicates that this is the default selected PaymentShippingOption in a sequence. User agents SHOULD display this option by default in the user interface.

13. PaymentComplete enum 

enum PaymentComplete {
    "fail",
    "success",
    "unknown"
};
"fail"
Indicates that processing of the payment failed. The user agent MAY display UI indicating failure.
"success"
Indicates the payment was successfully processed. The user agent MAY display UI indicating success.
"unknown"
The developer did not indicate success or failure and the user agent SHOULD NOT display UI indicating success or failure.

14. PaymentResponse interface 

[SecureContext,
 Exposed=Window]
interface PaymentResponse {
    [Default] object        toJSON();

    readonly attribute DOMString       requestId;
    readonly attribute DOMString       methodName;
    readonly attribute object          details;
    readonly attribute PaymentAddress? shippingAddress;
    readonly attribute DOMString?      shippingOption;
    readonly attribute DOMString?      payerName;
    readonly attribute DOMString?      payerEmail;
    readonly attribute DOMString?      payerPhone;

    Promise<void> complete(optional PaymentComplete result = "unknown");
};
Note

A PaymentResponse is returned when a user has selected a payment method and approved a payment request.

14.1 toJSON() method

When called, runs [WEBIDL]'s default toJSON operation.

14.2 methodName attribute

The payment method identifier for the payment method that the user selected to fulfill the transaction.

14.3 details attribute

An object or dictionary generated by a payment method that a merchant can use to process or validate a transaction (depending on the payment method).

Note

14.4 shippingAddress attribute

If the requestShipping member was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingAddress will be the full and final shipping address chosen by the user.

14.5 shippingOption attribute

If the requestShipping member was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingOption will be the id attribute of the selected shipping option.

14.6 payerName attribute

If the requestPayerName member was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerName will be the name provided by the user.

14.7 payerEmail attribute

If the requestPayerEmail member was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerEmail will be the email address chosen by the user.

14.8 payerPhone attribute

If the requestPayerPhone member was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerPhone will be the phone number chosen by the user.

14.9 requestId attribute

The corresponding payment request id that spawned this payment response.

14.10 complete() method

Note

The complete() method is called after the user has accepted the payment request and the [[acceptPromise]] has been resolved. Calling the complete() method tells the user agent that the payment interaction is over (and SHOULD cause any remaining user interface to be closed).

After the payment request has been accepted and the PaymentResponse returned to the caller but before the caller calls complete() the payment request user interface remains in a pending state. At this point the user interface ought not offer a cancel command because acceptance of the payment request has been returned. However, if something goes wrong and the developer never calls complete() then the user interface is blocked.

For this reason, implementations MAY impose a timeout for developers to call complete(). If the timeout expires then the implementation will behave as if complete() was called with no arguments.

The complete(result) method MUST act as follows:

  1. Let promise be a new Promise.
  2. If the value of the internal slot [[completeCalled]] is true, reject promise with an "InvalidStateError" DOMException.
  3. Otherwise, set the value of the internal slot [[completeCalled]] to true.
  4. Return promise and perform the remaining steps in parallel.
  5. Close down any remaining user interface. The user agent MAY use the value result to influence the user experience.
  6. Resolve promise with undefined.

14.11 Internal Slots

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

Internal Slot Description (non-normative)
[[completeCalled]] true if the complete method has been called and false otherwise.

15. PaymentRequest and iframe elements

This section is non-normative.

To indicate that a cross-origin iframe is allowed to invoke the payment request API, the allowpaymentrequest attribute can be specified on the iframe element.

16. Events

16.1 Summary

This section is non-normative.

Event name Interface Dispatched when…
shippingaddresschange PaymentRequestUpdateEvent The user provides a new shipping address.
shippingoptionchange PaymentRequestUpdateEvent The user chooses a new shipping option.

16.2 PaymentRequestUpdateEvent interface 

[Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict),
 SecureContext,
 Exposed=Window]
interface PaymentRequestUpdateEvent : Event {
    void updateWith(Promise<PaymentDetailsUpdate> detailsPromise);
};

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

16.2.1 Constructor

The PaymentRequestUpdateEvent(type, eventInitDict) constructor MUST act as follows:

  1. Let event be the result of constructing a PaymentRequestUpdateEvent instance with type and eventInitDict.
  2. Set event.[[waitForUpdate]] to false.
  3. Return event.

16.2.2 updateWith() method

Note

The updateWith(detailsPromise) method MUST act as follows:

  1. Let event be this PaymentRequestUpdateEvent instance.
  2. If event's isTrusted attribute is false, then then throw an "InvalidStateError" DOMException.
  3. If event.[[waitForUpdate]] is true, then throw an "InvalidStateError" DOMException.
  4. Let request be the value of event's target attribute.
  5. If request.[[state]] is not "interactive", then throw an "InvalidStateError" DOMException.
  6. If request.[[updating]] is true, then throw an "InvalidStateError" DOMException.
  7. Set event's stop propagation flag and stop immediate propagation flag.
  8. Set event.[[waitForUpdate]] to true.
  9. Set request.[[updating]] to true.
  10. 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 developers have made changes required by the change. Developers MUST settle the detailsPromise to indicate that the payment request is valid again.
  11. Run the update a PaymentRequest's details algorithm with detailsPromise and request.

16.2.3 Internal Slots

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

Internal Slot Description (non-normative)
[[waitForUpdate]] A boolean indicating whether an updateWith()-initiated update is currently in progress.

16.2.4 PaymentRequestUpdateEventInit dictionary 

dictionary PaymentRequestUpdateEventInit : EventInit {
};

17. Algorithms

When the internal slot [[state]] of a PaymentRequest object is set to "interactive", the user agent will trigger the following algorithms based on user interaction.

17.1 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. Queue a task on the user interaction task source to run the following steps:
    1. Let address be the result of running the steps to create a payment address.
    2. Set the shippingAddress attribute on request to address.
    3. Run the PaymentRequest updated algorithm with request and name.

17.2 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. Queue a task on the user interaction task source to run the following steps:
    1. Set the shippingOption attribute on request to the id string of the PaymentShippingOption provided by the user.
    2. Run the PaymentRequest updated algorithm with request and name.

17.3 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:

  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. The user agent SHOULD ensure that this never occurs.
  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 the result of creating an event using PaymentRequestUpdateEvent.
  4. Initialize event's type attribute to name.
  5. Dispatch event at request.
  6. If event.[[waitForUpdate]] is true, disable any part of the user interface that could cause another update event to be fired.

17.4 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 queue a task on the user interaction task source to perform 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", 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. The user agent SHOULD ensure that this never occurs.
  5. Let response be a new PaymentResponse.
  6. Set the requestId attribute value of response to the value of request.[[details]].id.
  7. Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
  8. Set the details attribute value of response to an object containing the payment method specific object that will be used by the merchant to process or validate the transaction. The format of this response will be defined for each payment method.
  9. If the requestShipping value of request.[[options]] is true, then set the shippingAddress attribute of response to the value of the shippingAddress attribute of request. Otherwise, set it to null.
  10. If the requestShipping value of request.[[options]] is true, then set the shippingOption attribute of response to the value of the shippingOption attribute of request. Otherwise, set it to null.
  11. 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, or to null if none was provided. Otherwise, set it to null.
  12. If the requestPayerEmail value of request.[[options]] is true, then set the payerEmail attribute of response to the payer's email address provided by the user, or to null if none was provided. Otherwise, set it to null.
  13. If the requestPayerPhone value of request.[[options]] is true, then set the payerPhone attribute of response to the payer's phone number provided by the user, or to null if none was provided. When setting the payerPhone value, the user agent SHOULD format the phone number to adhere to [E.164]. Otherwise, set it to null.
  14. Set response.[[completeCalled]] to false.
  15. Set request.[[state]] to "closed".
  16. Set the user agent's payment request is showing boolean to false.
  17. Resolve the pending promise request.[[acceptPromise]] with response.

17.5 User aborts the payment request algorithm

The user aborts the payment request algorithm runs when the user aborts the payment request through the currently interactive user interface. It MUST queue a task on the user interaction task source to perform 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", 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 "closed".
  5. Set the user agent's payment request is showing boolean to false.
  6. Reject the promise request.[[acceptPromise]] with an "AbortError" DOMException.

17.6 Update a PaymentRequest's details algorithm

The update a PaymentRequest's details algorithm takes a PaymentDetailsUpdate detailsPromise and a PaymentRequest request. The steps are conditional on the detailsPromise settling. If detailsPromise never settles then the payment request is blocked. Users SHOULD always be able to cancel a payment request. Implementations MAY choose to implement a timeout for pending updates if detailsPromise doesn't settle in a reasonable amount of time. If an implementation chooses to implement a timeout, they must execute the steps listed below in the "upon rejection" path. Such a timeout is a fatal error for the payment request.

  1. Upon rejection of detailsPromise:
    1. Abort the update with an "AbortError" DOMException.
  2. Upon fulfillment of detailsPromise with value value:
    1. Let details be the result of converting value to a PaymentDetailsUpdate dictionary. If this throws an exception, abort the update with the thrown exception.
    2. Let serializedModifierData be an empty list.
    3. Let selectedShippingOption be null.
    4. Let shippingOptions be an empty sequence<PaymentShippingOption>.
    5. Validate and canonicalize the details:
      1. If the total member of details is present, then:
        1. Check and canonicalize total details.total.amount. If an exception is thrown, then abort the update with that exception.
      2. If the displayItems member of details is present, then for each item in details.displayItems:
        1. Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with that exception.
      3. If the shippingOptions member of details is present, and request.[[options]].requestShipping is true, then:
        1. Set shippingOptions to details.shippingOptions.
        2. Let seenIDs be an empty list.
        3. For each option in shippingOptions:
          1. Check and canonicalize amount option.amount. If an exception is thrown, then abort the update with that exception.
          2. If seenIDs contains option.id, then abort the update with a TypeError.
          3. Otherwise, append option.id to seenIDs.
        4. For each option in shippingOptions:
          1. If option.selected is true, then set selectedShippingOption to option.id.
      4. If the modifiers member of details is present, then:
        1. Let modifiers be the sequence details.modifiers.
        2. Let serializedModifierData be an empty list.
        3. For each PaymentDetailsModifier modifier in modifiers:
          1. Run the steps to validate a payment method identifier with modifier.supportedMethods. If it returns false, then abort the update with a RangeError exception. Optional, inform the developer that the payment method identifier is invalid.
          2. If the total member of modifier is present, then:
            1. Check and canonicalize total modifier.total.amount. If an exception is thrown, then abort the update with that exception.
          3. If the additionalDisplayItems member of modifier is present, then for each PaymentItem item in modifier.additionalDisplayItems:
            1. Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with that exception.
          4. If the data member of modifier is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing modifier.data into a string. If JSON-serializing throws an exception, then abort the update with that exception.
          5. Add serializedData to serializedModifierData.
          6. Remove the data member of modifier, if it is present.
    6. Update the PaymentRequest using the new details:
      1. If the total member of details is present, then:
        1. Set request.[[details]].total to details.total.
      2. If the displayItems member of details is present, then:
        1. Set request.[[details]].displayItems to details.displayItems.
      3. If the shippingOptions member of details is present, and request.[[options]].requestShipping is true, then:
        1. Set request.[[details]].shippingOptions to shippingOptions.
        2. Set the value of request's shippingOption attribute to selectedShippingOption.
      4. If the modifiers member of details is present, then:
        1. Set request.[[details]].modifiers to details.modifiers.
        2. Set request.[[serializedModifierData]] to serializedModifierData.
      5. If request.[[options]].requestShipping is true, and request.[[details]].shippingOptions is empty, then the developer has signified that there are no valid shipping options for the currently-chosen shipping address (given by request's shippingAddress). In this case, the user agent SHOULD display an error indicating this, and MAY indicate that the currently-chosen shipping address is invalid in some way. The user agent SHOULD use the error member of details, if it is present, to give more information about why there are no valid shipping options for that address.
  3. In either case, run the following steps, after either the upon rejection or upon fulfillment steps have concluded:
    1. Set request.[[updating]] to false.
    2. The user agent SHOULD update the user interface based on any changed values in request. The user agent SHOULD re-enable user interface elements that might have been disabled in the steps above if appropriate.

If any of the above steps say to abort the update with an exception exception, then:

  1. Abort the current user interaction and close down any remaining user interface.
  2. Set request.[[state]] to "closed".
  3. Reject the promise request.[[acceptPromise]] with exception.
  4. Abort the algorithm.
Note

Aborting the update is performed when there is a fatal error updating the payment request, such as the supplied detailsPromise rejecting, or its fulfillment value containing invalid data. This would potentially leave the payment request in an inconsistent state since the developer hasn't successfully handled the change event. Consequently, the PaymentRequest moves to a "closed" state. The error is signaled to the developer through the rejection of the [[acceptPromise]], i.e., the promise returned by show().

User agents might show an error message to the user when this occurs.

18. Security Considerations

This section is non-normative.

18.1 Encryption of data fields

This section is non-normative.

The PaymentRequest API does not directly support encryption of data fields. Individual payment methods may choose to include support for encrypted data but it is not mandatory that all payment methods support this.

18.2 Payment Handler Matching

For security reasons, a user agent can limit matching (in show() and canMakePayment()) to payment handlers from the same origin as a URL payment method identifier. User agents can also use information provided by a payment method owner to match payment handlers from other origins.

19. Privacy Considerations

19.1 Exposing user information

The user agent MUST NOT share information about the user with a developer (e.g., the shipping address) without user consent.

The user agent MUST NOT share the values of the displayItems member or additionalDisplayItems member with a third-party payment handler without user consent.

20. Dependencies

This specification relies on several other underlying specifications.

Payment Method Identifiers
The term payment method identifier is defined by [payment-method-id]. It's an unique identifier for a payment method.
HTML
The following are defined by [HTML]: EventHandler, queue a task, user interaction task source, top-level browsing context, current settings object, allowed to use, triggered by user activation, in parallel, the iframe element, and the allowpaymentrequest attribute.
ECMAScript
The terms Promise, internal slot, RangeError, TypeError, and JSON.stringify are defined by [ECMASCRIPT].

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.

Writing Promise-Using Specifications
The terms upon fulfillment and upon rejection are defined by [PROMISES-GUIDE].
DOM
The Event interface, The EventInit dictionary, and the terms fire an event, dispatch flag, stop propagation flag, isTrusted attribute, and stop immediate propagation flag are defined by [DOM].
Web IDL

When this specification says to throw an error, the user agent must throw an error as described in [WEBIDL]. When this occurs in a sub-algorithm, this results in termination of execution of the sub-algorithm and all ancestor algorithms until one is reached that explicitly describes procedures for catching exceptions.

The algorithm for converting an ECMAScript value to a dictionary is defined by [WEBIDL].

DOMException and the following DOMException types from [WEBIDL] are used: "AbortError", "InvalidStateError", "NotAllowedError", "NotSupportedError", and "SecurityError".

21. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

There is only one class of product that can claim conformance to this specification: a user agent.

Note

Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner.

User agents MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

User agents MAY impose implementation-specific limits on otherwise unconstrained inputs, e.g., to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations. When an input exceeds implementation-specific limit, the user agent MUST throw, or, in the context of a promise, reject with, a TypeError optionally informing the developer of how a particular input exceeded an implementation-specific limit.

A. IDL Index

[Constructor(sequence<PaymentMethodData> methodData, PaymentDetailsInit details, optional PaymentOptions options),
 SecureContext,
 Exposed=Window]
interface PaymentRequest : EventTarget {
    Promise<PaymentResponse> show();
    Promise<void>            abort();
    Promise<boolean>         canMakePayment();

    readonly attribute DOMString            id;
    readonly attribute PaymentAddress?      shippingAddress;
    readonly attribute DOMString?           shippingOption;
    readonly attribute PaymentShippingType? shippingType;

             attribute EventHandler         onshippingaddresschange;

             attribute EventHandler         onshippingoptionchange;
};
dictionary PaymentMethodData {
    required DOMString supportedMethods;
             object    data;
};
dictionary PaymentCurrencyAmount {
    required DOMString currency;
    required DOMString value;
    // Note: currencySystem is "at risk" of being removed!
             DOMString currencySystem = "urn:iso:std:iso:4217";
};
dictionary PaymentDetailsBase {
    sequence<PaymentItem>            displayItems;
    sequence<PaymentShippingOption>  shippingOptions;
    sequence<PaymentDetailsModifier> modifiers;
};
dictionary PaymentDetailsInit : PaymentDetailsBase {
             DOMString   id;
    required PaymentItem total;
};
dictionary PaymentDetailsUpdate : PaymentDetailsBase {
    DOMString   error;
    PaymentItem total;
};
dictionary PaymentDetailsModifier {
    required DOMString             supportedMethods;
             PaymentItem           total;
             sequence<PaymentItem> additionalDisplayItems;
             object                data;
};
enum PaymentShippingType {
    "shipping",
    "delivery",
    "pickup"
};
dictionary PaymentOptions {
    boolean             requestPayerName = false;
    boolean             requestPayerEmail = false;
    boolean             requestPayerPhone = false;
    boolean             requestShipping = false;
    PaymentShippingType shippingType = "shipping";
};
dictionary PaymentItem {
    required DOMString             label;
    required PaymentCurrencyAmount amount;
             boolean               pending = false;
    // Note: type member is "at risk" of being removed!
             PaymentItemType       type;
};
enum PaymentItemType {
    "tax"
};
[SecureContext,
 Exposed=Window]
interface PaymentAddress {
    [Default] object toJSON();
    readonly attribute DOMString              country;
    readonly attribute FrozenArray<DOMString> addressLine;
    readonly attribute DOMString              region;
    readonly attribute DOMString              city;
    readonly attribute DOMString              dependentLocality;
    readonly attribute DOMString              postalCode;
    readonly attribute DOMString              sortingCode;
    readonly attribute DOMString              languageCode;
    readonly attribute DOMString              organization;
    readonly attribute DOMString              recipient;
    readonly attribute DOMString              phone;
};
dictionary PaymentShippingOption {
    required DOMString             id;
    required DOMString             label;
    required PaymentCurrencyAmount amount;
             boolean               selected = false;
};
enum PaymentComplete {
    "fail",
    "success",
    "unknown"
};
[SecureContext,
 Exposed=Window]
interface PaymentResponse {
    [Default] object        toJSON();

    readonly attribute DOMString       requestId;
    readonly attribute DOMString       methodName;
    readonly attribute object          details;
    readonly attribute PaymentAddress? shippingAddress;
    readonly attribute DOMString?      shippingOption;
    readonly attribute DOMString?      payerName;
    readonly attribute DOMString?      payerEmail;
    readonly attribute DOMString?      payerPhone;

    Promise<void> complete(optional PaymentComplete result = "unknown");
};
[Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict),
 SecureContext,
 Exposed=Window]
interface PaymentRequestUpdateEvent : Event {
    void updateWith(Promise<PaymentDetailsUpdate> detailsPromise);
};
dictionary PaymentRequestUpdateEventInit : EventInit {
};

B. Acknowledgements

This specification was derived from a report published previously by the Web Platform Incubator Community Group.

C. References

C.1 Normative references

[BCP47]
Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47
[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[E.164]
The international public telecommunication numbering plan. ITU-T. November 2010. Recommendation. URL: https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-E.164-201011-I!!PDF-E&type=items
[ecma-402]
ECMAScript Internationalization API Specification. Ecma International. URL: https://tc39.github.io/ecma402/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[ISO3166]
ISO 3166: Codes for the representation of names of countries and their subdivisions – Part 1: Country codes. International Organization for Standardization (ISO). November 2013. Published. URL: https://www.iso.org/standard/63545.html
[ISO4217]
Currency codes - ISO 4217. ISO. 2015. International Standard. URL: http://www.iso.org/iso/home/standards/currency_codes.htm
[payment-method-id]
Payment Method Identifiers. Adrian Bateman; Zach Koch; Roy McElmurry; Marcos Caceres. W3C. 14 September 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/payment-method-id/
[PROMISES-GUIDE]
Writing Promise-Using Specifications. Domenic Denicola. W3C. 16 February 2016. Finding of the W3C TAG. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4122
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

C.2 Informative references

[fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[payment-method-basic-card]
Basic Card Payment. Adrian Bateman; Zach Koch; Roy McElmurry; Marcos Caceres. W3C. 27 July 2017. W3C Working Draft. URL: https://www.w3.org/TR/payment-method-basic-card/
[rfc6454]
The Web Origin Concept. A. Barth. IETF. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6454