Payment Request API

W3C Editor's Draft

This version:
https://w3c.github.io/payment-request/
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/test-results/payment-request/all.html
Editors:
Marcos Cáceres (Mozilla)
Domenic Denicola (Google)
Zach Koch (Google)
Roy McElmurry (Facebook)
Ian Jacobs ( W3C )
Rouslan Solomakhin ( Google )
Former editor:
Adrian Bateman (Microsoft Corporation)
Participate:
GitHub w3c/payment-request
File a bug
Commit history
Pull requests
Can I Use this API?
caniuse.com

Copyright © 2019 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 is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/payment-request/ for the Editor's draft.

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 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 an Editor's Draft.

GitHub Issues are preferred for discussion of this specification.

Please see the Working Group's implementation report .

Publication as an Editor's Draft 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 March 2019 W3C Process Document .

Changes since last publication

Substantive changes to the Payment Request API since the 9 July 2018 version are as follows. The complete list of changes, including all editorial changes, is viewable in the commit history .

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 is an implementation detail of a payment handler . Concretely, each payment handler defines:

Steps to check if a payment can be made :
How a payment handler determines whether it, or the user, can potentially "make a payment" is also an implementation detail of a payment handler. For an example, see the can make payment algorithm of [ payment-method-basic-card ].
Steps to respond to a payment request :
Steps that return an object or dictionary that a merchant uses to process or validate the transaction. The structure of this object is specific to each payment method . For an example of such an object, see the BasicCardResponse dictionary of [ payment-method-basic-card ].
Steps for when a user changes payment method (optional)
Steps that describe how to handle the user changing payment method or monetary instrument (e.g., from a debit card to a credit card) that results in a dictionary or object or null.

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 and scope

The following are out of scope for this specification:

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 Declaring multiple ways of paying

When constructing a new PaymentRequest , a merchant uses the first argument ( methodData ) to list the different ways a user can pay for things (e.g., credit cards, Apple Pay, Google Pay, etc.). More specifically, the methodData sequence contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the merchant accepts and any associated payment method specific data (e.g., which credit card networks are supported).

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

2.2 Describing what is being paid for

When constructing a new PaymentRequest , a merchant uses the second argument of the constructor ( details ) to provide the details of the transaction that the user is being asked to complete. This includes the total of the order and, optionally, some line items that can provide a detailed breakdown of what is being paid for.

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.3 Adding 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.4 Conditional modifications to payment request

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

Example 4 : Modifying payment request based on card type 
// Certain cards incurs a $3.00 processing fee.
const cardFee = {
  label: "Card processing fee",
  amount: { currency: "USD", value: "3.00" },
};
// Modifiers apply when the user chooses to pay with
// a card.
const modifiers = [
  {
    additionalDisplayItems: [cardFee],
    supportedMethods: "basic-card",
    total: {
      label: "Total due",
      amount: { currency: "USD", value: "68.00" },
    },
    data: {
      supportedNetworks: networks,
    },
  },
];

Object
.assign(details,
{
modifiers
});

2.5 Requesting specific information from the end user

Some financial transactions require a user to provide specific information in order for a merchant to fulfill a purchase (e.g., the user's shipping address, in case a physical good needs to be shipped). To request this information, a merchant can pass a third optional argument ( options ) to the PaymentRequest constructor indicating what information they require. When the payment request is shown, the user agent will request this information from the end user and return it to the merchant when the user accepts the payment request.

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

2.6 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 {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await request.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong...
    await response.complete("fail");
  }
}
doPaymentRequest();

2.7 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 => {
  // selected shipping option
  const { shippingOption } = request;
  const newTotal = {
    currency: "USD",
    label: "Total due",
    value: calculateNewTotal(shippingOption),
  };
  ev.updateWith({ total: newTotal });
};
async function checkShipping(request) {
  try {
    const json = request.shippingAddress.toJSON();
    await ensureCanShipTo(json);
    const { shippingOptions, total } = await calculateShipping(json);
    return { shippingOptions, total };
  } catch (err) {
    return { error: `Sorry! we can't ship to your address.` };
  }
}

2.8 Fine-grained error reporting

A developer can use the shippingAddressErrors member of the PaymentDetailsUpdate dictionary to indicate that there are validation errors with specific attributes of a PaymentAddress . The shippingAddressErrors member is a AddressErrors dictionary, whose members specifically demarcate the fields of a physical address that are erroneous while also providing helpful error messages to be displayed to the end user.

Example 8 
request.onshippingaddresschange = ev => {
  ev.updateWith(validateAddress(request.shippingAddress));
};
function validateAddress(shippingAddress) {
  const error = "Can't ship to this address.";
  const shippingAddressErrors = {
    city: "FarmVille is not a real place.",
    postalCode: "Unknown postal code for your country.",
  };
  // Empty shippingOptions implies that we can't ship
  // to this address.
  const shippingOptions = [];
  return { error, shippingAddressErrors, shippingOptions };
}

2.9 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 9 : 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 {
  [NewObject]
  Promise<PaymentResponse> show(optional Promise<PaymentDetailsUpdate> detailsPromise);
  [NewObject]
  Promise abort();
  [NewObject]
  Promise<boolean> canMakePayment();
  readonly attribute DOMString id;
  readonly attribute PaymentAddress? shippingAddress;
  readonly attribute DOMString? shippingOption;
  readonly attribute PaymentShippingType? shippingType;
  attribute EventHandler onmerchantvalidation;
  attribute EventHandler onshippingaddresschange;
  attribute EventHandler onshippingoptionchange;
  attribute EventHandler onpaymentmethodchange;
};
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.

A request 's payment-relevant browsing context is that PaymentRequest 's relevant global object 's browsing context's top-level browsing context . Every payment-relevant browsing context has a payment request is showing boolean, which prevents showing more than one payment UI at a time.

The payment request is showing boolean simply prevents more than one payment UI being shown in a single browser tab. However, a payment handler can restrict the user agent to showing only one payment UI across all browser windows and tabs. Other payment handlers might allow showing a payment UI across disparate browser tabs.

3.1 Constructor

The PaymentRequest is constructed using the supplied sequence of PaymentMethodData methodData including any payment method specific data , the PaymentDetailsInit details , and the PaymentOptions 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 " payment " feature, then throw a " SecurityError " DOMException .
  2. 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 ].
  3. Let serializedMethodData be an empty list.
  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. 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. If serializedData is not null, and if required by the specification that defines the paymentMethod . supportedMethods :
        1. Let object be the result of JSON-parsing serializedData .

        2. Convert object to an IDL value of the type specified by the specification that defines the paymentMethod . supportedMethods (e.g., a BasicCardRequest in the case of [ payment-method-basic-card ]). Rethrow any exceptions.

          Note

          This step assures that any IDL type conversion errors are caught as early as possible.

      4. Add the tuple ( paymentMethod . supportedMethods , serializedData ) to serializedMethodData .
  5. Process the total:
    1. Check and canonicalize total amount 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 set.
      2. For each option in details . shippingOptions :
        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. 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 amount 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 the tuple ( modifier . supportedMethods , 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 request . [[response]] to null.
  19. Set the value of request 's shippingOption attribute to selectedShippingOption .
  20. Set the value of the shippingAddress attribute on request to null.
  21. 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.
  22. 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.

Each payment handler controls what happens when multiple browsing context simultaneously call the show() method. For instance, some payment handlers will allow multiple payment UIs to be shown in different browser tabs/windows. Other payment handlers might only allow a single payment UI to be shown for the entire user agent.

The show(optional detailsPromise ) method MUST act as follows:

  1. If the method was not triggered by user activation , return a promise rejected with with a " SecurityError " DOMException .
  2. Let request be the context object .
  3. Let document be request 's relevant global object 's associated Document .
  4. If document is not fully active , then return a promise rejected with an " AbortError " DOMException .

  5. 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 limit the rate at which a page can call show() , as described in section § 20. § 19. Privacy and Security Considerations .

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

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

  12. Set request 's payment-relevant browsing context 's payment request is showing boolean to true.
  13. Return acceptPromise and perform the remaining steps in parallel .
  14. Let handlers be an empty list .
  15. 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 identifier , then convert data to an IDL value of the type specified there. Otherwise, convert to object .
    4. If conversion results in an exception error :
      1. Set request . [[state]] to " closed ".
      2. Reject acceptPromise with error .
      3. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
      4. Terminate this algorithm.
    5. Let registeredHandlers be a list of registered payment handlers for the payment method identifier .
    6. For each handler in registeredHandlers :
      1. Let canMakePayment be the result of running handler 's steps to check if a payment can be made with data .
      2. If canMakePayment is true, then append handler to handlers .
  16. If handlers is empty, then:
    1. Set request . [[state]] to " closed ".
    2. Reject acceptPromise with " NotSupportedError " DOMException .
    3. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    4. Terminate this algorithm.
  17. Present a user interface that will 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 .
  18. If detailsPromise was passed, then:
    1. Run the update a PaymentRequest 's details algorithm with detailsPromise , request , and null.
    2. Wait for the detailsPromise to settle.
      Note

      Based on how the detailsPromise settles, the update a PaymentRequest 's details algorithm determines how the payment UI behaves. That is, upon rejection of the detailsPromise , the payment request aborts. Otherwise, upon fulfillment detailsPromise , the user agent re-enables the payment request UI and the payment flow can continue.

  19. Let handler be the payment handler selected by the end-user.
  20. Let modifiers be an empty list.
  21. For each tuple in [[serializedModifierData]] :
    1. If the first element of tuple (a PMI ) matches the payment method identifier of handler , then append the second element of tuple (the serialized method data) to modifiers .

  22. Pass the converted second element in the paymentMethod tuple and modifiers . 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 other internal slots of request (some MAY be excluded for privacy reasons where appropriate).

    Handling of multiple applicable modifiers in the [[serializedModifierData]] internal slot is payment handler specific and beyond the scope of this specification. Nevertheless, it is RECOMMENDED that payment handlers use a "last one wins" approach with items in the [[serializedModifierData]] list: that is to say, an item at the end of the list always takes precedence over any item at the beginning of the list (see example below).

    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:

    1. Close down the user interface.
    2. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    3. Reject acceptPromise 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 context object .
  2. If request . [[response]] is not null, and request . [[response]] . [[retryPromise]] is not null, return a promise rejected with an " InvalidStateError " DOMException .
  3. If the value of request . [[state]] is not " interactive " then return a promise rejected with an " InvalidStateError " DOMException .
  4. Let promise be a new promise .
  5. Return promise and perform the remaining steps in parallel .
  6. Try to abort the current user interaction with the payment handler and close down any remaining user interface.
  7. 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 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 top-level browsing context 's discretion, return a promise rejected with a " NotAllowedError " DOMException . Note As described in section This allows , the user agents to apply heuristics to detect and prevent abuse of agent may limit the canMakePayment() method for fingerprinting purposes, such as creating PaymentRequest objects with rate at which a variety of supported payment methods and calling page can call 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 hasHandlerPromise be a new promise .
  5. Return hasHandlerPromise , and perform the remaining steps in parallel .
  6. For each paymentMethod tuple in request . [[serializedMethodData]] :
    1. Let identifier be the first element in the paymentMethod tuple.
    2. If the user agent has a payment handler that supports handling payment requests for identifier , resolve hasHandlerPromise with true and terminate this algorithm.
  7. Resolve hasHandlerPromise 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 onmerchantvalidation attribute

A PaymentRequest 's onmerchantvalidation attribute is an EventHandler for a MerchantValidationEvent named " merchantvalidation ".

3.9 onshippingaddresschange attribute

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

3.10 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.11 onshippingoptionchange attribute

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

3.12 onpaymentmethodchange attribute

A PaymentRequest 's onpaymentmethodchange attribute is an EventHandler for a PaymentMethodChangeEvent named " paymentmethodchange ".

3.13 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 if 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.
[[response]] Null, or the PaymentResponse instantiated by this PaymentRequest .

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;
};

A PaymentCurrencyAmount dictionary is used to supply monetary amounts.

currency member

An [ ISO4217 ] well-formed 3-letter alphabetic code (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).

Note : Digital currencies and ISO 4217 currency codes

User agents implementing this specification enforce [ ISO4217 ]'s 3-letter codes format via ECMAScript’s isWellFormedCurrencyCode abstract operation, which is invoked as part of the check and canonicalize amount algorithm. When a code does not adhere to the [ ISO4217 ] defined format, a RangeError is thrown.

Current implementations will therefore allow the use of well-formed currency codes that are not part of the official [ ISO4217 ] list (e.g., XBT, XRP, etc.). If the provided code is a currency that the browser knows how to display, then an implementation will generally display the appropriate currency symbol in the user interface (e.g., "USD" is shown as "$", "GBP" is "£", and the non-standard "XBT" could be shown as "Ƀ"). When a code cannot be matched, the specification recommends browsers show a scarab "¤".

Efforts are underway at ISO to account for digital currencies, which may result in an update to the [ ISO4217 ] registry or an entirely new registry. The community expects this will resolve ambiguities that have crept in through the use of non-standard 3-letter codes; for example, does "BTC" refer to Bitcoin or to a future Bhutan currency? At the time of publication, it remains unclear what form this evolution will take, or even the time frame in which the work will be completed. The W3C Web Payments Working Group is liaising with ISO so that, in the future, revisions to this specification remain compatible with relevant ISO registries.

value member
A valid decimal monetary value containing a monetary amount.
Example 11 : How to represent US$55.00 
{
  "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:

  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 the result of IsWellFormedCurrencyCode ( amount . currency ) is false, then throw a RangeError exception, optionally informing the developer that the currency is invalid.
  2. If amount . value is not a valid decimal monetary value , throw a TypeError , optionally informing the developer that the currency is invalid.
  3. Set amount . currency to the result of ASCII uppercasing amount . currency .

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

  1. Check and canonicalize amount amount . Rethrow any exceptions.
  2. If the first code point of amount . value is U+002D (-), then throw a TypeError optionally informing the developer that a total's value 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 and 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;
  AddressErrors shippingAddressErrors;
  PayerErrors payerErrors;
  object paymentMethodErrors;
};

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 that explains why goods cannot be shipped to the chosen shipping address, or any other reason why no shipping options are available. 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).
total member
A PaymentItem containing a non-negative amount .
Note

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

shippingAddressErrors member
Represents validation errors with the shipping address that is associated with the event target .
payerErrors member
Validation errors related to the payer details .
paymentMethodErrors member

Payment method specific errors. See, for example, [ payment-method-basic-card ]'s BasicCardErrors .

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 the destination 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 requestBillingAddress = 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.

requestBillingAddress member
A boolean that instructs the user agent to get the billing address associated with a payment method (e.g., the billing address associated with a credit card). Typically, the user agent will return the billing address as part of the PaymentMethodChangeEvent 's methodDetails , albeit possibly with parts of the address redacted for privacy reasons. A merchant can use this information to, for example, calculate tax in certain jurisdictions.
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 PaymentShippingType 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;
};

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.

11. Physical addresses

A physical address is composed of the following parts.

Address line
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.
City
The city/town portion of the address.
Country
The country corresponding to the address.
Dependent locality
The dependent locality or sublocality within a city. For example, neighborhoods, boroughs, districts, or UK dependent localities.
Organization
The organization, firm, company, or institution at the address.
Phone number
The phone number of the recipient or contact person at the address.
Postal code
The postal code or ZIP code, also known as PIN code in India.
Recipient
The name of the recipient or contact person at the address.
Region
The top level administrative subdivision of the country. For example, this can be a state, a province, an oblast, or a prefecture.
Sorting code
The sorting code as used in, for example, France.

11.1 PaymentAddress interface 

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

The PaymentAddress interface represents a physical address .

Note : What happened to regionCode?

11.1.1 Internal constructor

The steps to internally construct a PaymentAddress with an optional AddressInit details are given by the following algorithm:

  1. Let address be a new instance of PaymentAddress .
  2. Set address . [[addressLine]] to the empty frozen array, and all other internal slots to the empty string.
  3. If details was not passed, return address .
  4. If details [" country "] is present and not the empty string:
    1. Set country the result of strip leading and trailing ASCII whitespace from details [" country "] and performing ASCII uppercasing .
    2. If country is not a valid [ ISO3166-1 ] alpha-2 code, throw a RangeError exception.
    3. Set address . [[country]] to country .
  5. Let cleanAddressLines be an empty list.
  6. If details [" addressLine "] is present, then for each item in details [" addressLine "]:
    1. Strip leading and trailing ASCII whitespace from item and append the result into cleanAddressLines .
  7. Set address . [[addressLine]] to a new frozen array created from cleanAddressLines .
  8. If details [" region "] is present, strip leading and trailing ASCII whitespace from details [" region "] and set address . [[region]] to the result.
  9. If details [" city "] is present, strip leading and trailing ASCII whitespace from details [" city "] and set address . [[city]] to the result.
  10. If details [" dependentLocality "] is present, strip leading and trailing ASCII whitespace from details [" dependentLocality "] and set address . [[dependentLocality]] to the result.
  11. If details [" postalCode "] is present, strip leading and trailing ASCII whitespace from details [" postalCode "] and set address . [[postalCode]] to the result.
  12. If details [" sortingCode "] is present, strip leading and trailing ASCII whitespace from details [" sortingCode "] and set address . [[sortingCode]] to the result.
  13. If details [" organization "] is present, strip leading and trailing ASCII whitespace from details [" organization "] and set address . [[organization]] to the result.
  14. If details [" recipient "] is present, strip leading and trailing ASCII whitespace from details [" recipient "] and set address . [[recipient]] to the result.
  15. If details [" phone "] is present, strip leading and trailing ASCII whitespace from details [" phone "] and set address . [[phone]] to the result.
  16. Return address .

11.1.2 toJSON() method

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

11.1.3 country attribute

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

11.1.4 addressLine attribute

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

11.1.5 region attribute

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

11.1.6 city attribute

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

11.1.7 dependentLocality attribute

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

11.1.8 postalCode attribute

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

11.1.9 sortingCode attribute

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

11.1.10 organization attribute

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

11.1.11 recipient attribute

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

11.1.12 phone attribute

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

11.1.13 Internal slots

Internal slot Description ( non-normative )
[[country]] A country as an [ ISO3166-1 ] alpha-2 code stored in its canonical uppercase form or the empty string. For example, "JP".
[[addressLine]] A frozen array, possibly of zero length, representing an address line .
[[region]] A region as a country subdivision name or the empty string, such as "Victoria", representing the state of Victoria in Australia.
[[city]] A city or the empty string.
[[dependentLocality]] A dependent locality or the empty string.
[[postalCode]] A postal code or the empty string.
[[sortingCode]] A sorting code or the empty string.
[[organization]] An organization or the empty string.
[[recipient]] A recipient or the empty string.
[[phone]] A phone number or the empty string.

11.2 AddressInit dictionary 

dictionary AddressInit {
  DOMString country;
  sequence<DOMString> addressLine;
  DOMString region;
  DOMString city;
  DOMString dependentLocality;
  DOMString postalCode;
  DOMString sortingCode;
  DOMString organization;
  DOMString recipient;
  DOMString phone;
};

An AddressInit is passed when constructing a PaymentAddress . Its members are as follows.

addressLine member
An address line , represented as a sequence.
city member
A city .
country member
An country , represented as a [ ISO3166-1 ] country code.
dependentLocality member
A dependent locality .
organization member
An organization .
phone member
A phone number , optionally structured to adhere to [ E.164 ].
postalCode member
A postal code .
recipient member
A recipient . Under certain circumstances, this member may contain multiline information. For example, it might contain "care of" information.
region member
A region .
sortingCode member
A sorting code .

11.3 AddressErrors dictionary 

dictionary AddressErrors {
  DOMString addressLine;
  DOMString city;
  DOMString country;
  DOMString dependentLocality;
  DOMString organization;
  DOMString phone;
  DOMString postalCode;
  DOMString recipient;
  DOMString region;
  DOMString sortingCode;
};

The members of the AddressErrors dictionary represent validation errors with specific parts of a physical address . Each dictionary member has a dual function: firstly, its presence denotes that a particular part of an address is suffering from a validation error. Secondly, the string value allows the developer to describe the validation error (and possibly how the end user can fix the error).

Note

Developers need to be aware that users might not have the ability to fix certain parts of an address. As such, they need to be mindful not to ask the user to fix things they might not have control over.

addressLine member
Denotes that the address line has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's addressLine attribute's value.
city member
Denotes that the city has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's city attribute's value.
country member
Denotes that the country has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's country attribute's value.
dependentLocality member
Denotes that the dependent locality has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's dependentLocality attribute's value.
organization member
Denotes that the organization has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's organization attribute's value.
phone member
Denotes that the phone number has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's phone attribute's value.
postalCode member
Denotes that the postal code has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's postalCode attribute's value.
recipient member
Denotes that the recipient has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's addressLine attribute's value.
region member
Denotes that the region has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's region attribute's value.
sortingCode member
The sorting code has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress 's sortingCode attribute's value.

11.4 Creating a PaymentAddress from user-provided input

The steps to create a PaymentAddress from user-provided input are given by the following algorithm. The algorithm takes a list redactList .

Note : Privacy of recipient information (the redactList)

The redactList optionally gives user agents the possibility to limit the amount of personal information about the recipient that the API shares with the merchant.

For merchants, the resulting PaymentAddress object provides enough information to, for example, calculate shipping costs, but, in most cases, not enough information to physically locate and uniquely identify the recipient.

Unfortunately, even with the redactList , recipient anonymity cannot be assured. This is because in some countries postal codes are so fine-grained that they can uniquely identify a recipient.

  1. Let details be an AddressInit dictionary with no members present.
  2. If "addressLine" is not in redactList , set details [" addressLine "] to the result of splitting the user-provided address line into a list . If none was provided, set it to the empty list .
    Note
  3. If "country" is not in redactList , set details [" country "] to the user-provided country as an upper case [ ISO3166-1 ] alpha-2 code, or to the empty string if none was provided.
  4. If "phone" is not in redactList , set details [" phone "] to the user-provided phone number, or to the empty string if none was provided.
    Note : Privacy of phone number
  5. If "city" is not in redactList , set details [" city "] to the user-provided city, or to the empty string if none was provided.
  6. If "dependentLocality" is not in redactList , set details [" dependentLocality "] to the user-provided dependent locality, or to the empty string if none was provided.
  7. If "organization" is not in redactList , set details [" organization "] to the user-provided recipient organization, or to the empty string if none was provided.
  8. If "postalCode" is not in redactList , set details [" postalCode "] to the user-provided postal code, or to the empty string if none was provided. Optionally, redact part of details [" postalCode "].
    Note : Privacy of Postal Codes

    Postal codes in certain countries can be so specific as to uniquely identify an individual. This being a privacy concern, some user agents only return the part of a postal code that they deem sufficient for a merchant to calculate shipping costs. This varies across countries and regions, and so the choice to redact part, or all, of the postal code is left to the discretion of implementers in the interest of protecting users' privacy.

  9. If "recipient" is not in redactList , set details [" recipient "] to the user-provided recipient of the transaction, or to the empty string if none was provided.

  10. If "region" is not in redactList :

    Note : Countries where regions are not commonly used

    In some countries (e.g., Belgium) it is uncommon for users to include a region as part of a physical address (even if all the regions of a country are part of [ ISO3166-2 ]). As such, when the user agent knows that the user is inputting the address for a particular country, it might not provide a field for the user to input a region . In such cases, the user agent returns an empty string for both PaymentAddress 's region attribute - but the address can still serve its intended purpose (e.g., be valid for shipping or billing purposes).

    1. Set details [" region "] to the user-provided region, or to the empty string if none was provided.
  11. If "sortingCode" is not in redactList , set details [" sortingCode "] to the user-provided sorting code, or to the empty string if none was provided.
  12. Internally construct a new PaymentAddress with details and return the result.

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 : EventTarget  {
  [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;
  [NewObject]
  Promise complete(optional PaymentComplete result = "unknown");
  [NewObject]
  Promise retry(optional PaymentValidationErrors errorFields);
  attribute EventHandler onpayerdetailchange;
};
Note

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

14.1 retry() method

The retry( errorFields ) method MUST act as follows:

  1. Let response be the context object .
  2. Let request be response . [[request]] .
  3. Let document be request 's relevant global object 's associated Document .
  4. If document is not fully active , then return a promise rejected with an " AbortError " DOMException .
  5. If response . [[complete]] is true, return a promise rejected with an " InvalidStateError " DOMException .
  6. If response . [[retryPromise]] is not null, return a promise rejected with an " InvalidStateError " DOMException .
  7. Set request . [[state]] to " interactive ".
  8. Let retryPromise be a new promise .
  9. Set response . [[retryPromise]] to retryPromise .
  10. If errorFields was passed:
    1. Optionally, show a warning in the developer console if any of the following are true:
      1. request . [[options]] [" requestPayerName "] is false, and errorFields [" payer "][" name "] is present.
      2. request . [[options]] [" requestPayerEmail "] is false, and errorFields [" payer "][" email "] is present.
      3. request . [[options]] [" requestPayerPhone "] is false, and errorFields [" payer "][" phone "] is present.
      4. request . [[options]] [" requestShipping "] is false, and errorFields [" shippingAddress "] is present.
    2. If errorFields [" paymentMethod ] member was passed, and if required by the specification that defines response 's payment method , then convert errorFields 's paymentMethod member to an IDL value of the type specified there. Otherwise, convert to object .
    3. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    4. If conversion results in a exception error :
      1. Reject retryPromise with error .
      2. Set user agent 's payment request is showing boolean to false.
      3. Return.
    5. By matching the members of errorFields to input fields in the user agent's UI, indicate to the end user that something is wrong with the data of the payment response. For example, a user agent might draw the user's attention to the erroneous errorFields in the browser's UI and display the value of each field in a manner that helps the user fix each error. Similarly, if the error member is passed, present the error in the user agent's UI. In the case where the value of a member is the empty string, the user agent MAY substitute a value with a suitable error message.
  11. Otherwise, if errorFields was not passed, signal to the end user to attempt to retry the payment. Re-enable any UI element that affords the end user the ability to retry accepting the payment request.
  12. 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:
    1. Close down the user interface.
    2. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    3. Reject retryPromise with an " AbortError " DOMException .
  13. Finally, when retryPromise settles, set response . [[retryPromise]] to null.
  14. Return retryPromise .
    Note

    The retryPromise will later be resolved by the user accepts the payment request algorithm , or rejected by either the user aborts the payment request algorithm or abort the update .

14.1.1 PaymentValidationErrors dictionary 

dictionary PaymentValidationErrors {
  PayerErrors payer;
  AddressErrors shippingAddress;
  DOMString error;
  object paymentMethod;
};
payer member
Validation errors related to the payer details .
shippingAddress member
Represents validation errors with the PaymentResponse 's shippingAddress .
error member
A general description of an error with the payment from which the user can attempt to recover. For example, the user may recover by retrying the payment. A developer can optionally pass the error member on its own to give a general overview of validation issues, or it can be passed in combination with other members of the PaymentValidationErrors dictionary.
paymentMethod member
A payment method specific errors. See, for example, [ payment-method-basic-card ]'s BasicCardErrors .

14.1.2 PayerErrors dictionary 

dictionary PayerErrors {
  DOMString email;
  DOMString name;
  DOMString phone;
};

The PayerErrors is used to represent validation errors with one or more payer details .

Payer details are any of the payer's name, payer's phone number, and payer's email.

email member
Denotes that the payer's email suffers from a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentResponse 's payerEmail attribute's value.
name member
Denotes that the payer's name suffers from a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentResponse 's payerName attribute's value.
phone member
Denotes that the payer's phone number suffers from a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentResponse 's payerPhone attribute's value.

14.2 toJSON() method

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

14.3 methodName attribute

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

14.4 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.5 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.6 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.7 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.8 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.9 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.10 requestId attribute

The corresponding payment request id that spawned this payment response.

14.11 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 SHOULD 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 response be the context object .
  2. If response . [[complete]] is true, return a promise rejected with an " InvalidStateError " DOMException .
  3. If response . [[retryPromise]] is not null, return a promise rejected with an " InvalidStateError " DOMException .
  4. Let promise be a new promise .
  5. Set response . [[complete]] to true.
  6. Return promise and perform the remaining steps in parallel .
  7. 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:
    1. Close down the user interface.
    2. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    3. Reject promise with an " AbortError " DOMException .
  8. Otherwise:
    1. Close down any remaining user interface. The user agent MAY use the value result to influence the user experience.
    2. Set request 's payment-relevant browsing context 's payment request is showing boolean to false.
    3. Resolve promise with undefined.

14.12 onpayerdetailchange attribute

Allows a developer to handle " payerdetailchange " events.

14.13 Internal Slots

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

Internal Slot Description ( non-normative )
[[complete]] Is true if the request for payment has completed (i.e., complete() was called, or there was a fatal error that made the response not longer usable), or false otherwise.
[[request]] The PaymentRequest instance that instantiated this PaymentResponse .
[[retryPromise]] Null, or a Promise that resolves when a user accepts the payment request or rejects if the user aborts the payment request .

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. See § 16. Feature Policy integration for details of how allowpaymentrequest and Feature Policy interact.

16. Feature Policy integration

This specification defines a policy-controlled feature identified by the string " payment ". Its default allowlist is ' self '.

Note

A document ’s feature policy determines whether any content in that document is allowed to construct PaymentRequest instances. If disabled in any document, no content in the document will be allowed to use the PaymentRequest constructor (trying to create an instance will throw).

The allowpaymentrequest attribute of the HTML iframe element affects the container policy for any document nested in that iframe. Unless overridden by the allow attribute, setting allowpaymentrequest on an iframe is equivalent to