Payment Request API

1.1 Goals

Allow the user agent to act as intermediary between merchants, users, and payment methods
Standardize (to the extent that it makes sense) the communication flow between a merchant, user agent, and payment method
Allow payment methods to bring more secure payment transactions to the web

1.1.1 Out of scope

Create a new payment method
Integrate directly with payment processors

2. Definitions

A string is a valid decimal monetary value if it consists of the following components in the given order:

Optionally, a single U+002D HYPHEN-MINUS character (-), to indicate that the amount is negative
One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)
Optionally, a single U+002E FULL STOP character (.) followed by one or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)

Note

The following regular expression is an implementation of the above definition.

^-?[0-9]+(\.[0-9]+)?$

3. `PaymentRequest` interface

[Constructor(sequence<PaymentMethodData> methodData, PaymentDetailsInit details, optional PaymentOptions options),
 SecureContext]
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;
};

A web page creates a PaymentRequest to make a payment request. This is typically associated with the user initiating a payment process (e.g., selecting a "Power Up" in an interactive game, pulling up to an automated kiosk in a parking structure, or activating a "Buy", "Purchase", or "Checkout" button). The PaymentRequest allows the web page to exchange information with the user agent while the user is providing input before approving or denying a payment request.

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

The following example shows how to construct a PaymentRequest and begin the user interaction:

Example 1: Constructing a PaymentRequest object

function validateResponse(response){
  // check that the response is ok... throw if bad, for example.
}

async function doPaymentRequest() {
  const payment = new PaymentRequest(methodData, details, options);
  payment.addEventListener("shippingaddresschange", event => {
      // Process shipping address change
  });
  let paymentResponse;
  try {
    paymentResponse = await payment.show();
    // paymentResponse.methodName contains the selected payment method.
    // paymentResponse.details contains a payment method specific
    // response.
    validateResponse(paymentResponse);
    paymentResponse.complete("success");
  } catch (err) {
    console.error("Uh oh, bad payment response!", err.message);
    paymentResponse.complete("fail");
  }
}
doPaymentRequest();

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 methodData supplied to the PaymentRequest constructor SHOULD be in the order of preference of the caller.

Note

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 2: The 'methodData' argument

const methodData = [{
  supportedMethods: ["basic-card"],
  data: {
    supportedNetworks: ['aFamousBrand', 'aDebitNetwork'],
    supportedTypes: ['debit']
  }
}, {
  supportedMethods: ["bobpay.com"],
  data: {
    merchantIdentifier: "XXXX",
    bobPaySpecificField: true
  }
}];
const request = new PaymentRequest(methodData, details, options);

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

Example 3: The 'details' argument

const details = {
  id: "super-store-order-123-12312",
  displayItems: [
    {
      label: "Sub-total",
      amount: { currency: "USD", value : "55.00" }, // US$55.00
    },
    {
      label: "Sales Tax",
      amount: { currency: "USD", value : "5.00" }, // US$5.00
    }
  ],
  total: {
    label: "Total due",
    amount: { currency: "USD", value : "60.00" }, // US$60.00
  }
}
const request = new PaymentRequest(methodData, details, options);

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

Example 4: The 'options' argument

const options = {
  requestShipping: true
}
const request = new PaymentRequest(methodData, details, options);

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

If a paymentRequestId was not provided during construction, generate a paymentRequestId.
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.
Let serializedMethodData be an empty list.
Establish the request's id:
1. If details.id is missing, add an id member to details and set its value to string that uniquely identifies this payment request. It is RECOMMENDED that the string be a UUID [RFC4122].
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. If the length of the paymentMethod.supportedMethods sequence is zero, then throw a TypeError, optionally informing the developer that each payment method needs to include at least one payment method identifier.
  2. Let serializedData be the result of JSON-serializing paymentMethod.data into a string, if the data member of paymentMethod is present, or null if it is not. Rethrow any exceptions.
  3. Add the tuple (paymentMethod.supportedMethods, serializedData) to serializedMethodData.
Process the total:
1. If details.total.amount.value is not a valid decimal monetary value, then throw a TypeError; optionally informing the developer that the value is invalid.
2. If the first character of details.total.amount.value is U+002D HYPHEN-MINUS, then throw a TypeError, optionally informing the developer that the total can't be negative.
If the displayItems member of details is present, then for each item in details.displayItems:
1. If item.amount.value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
Let selectedShippingOption be null.
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. If option.amount.value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
    2. If seenIDs contains option.id, then set options to an empty sequence and break.
    3. Append option.id to seenIDs.
  4. For each option in options (which may have been reset to the empty sequence in the previous step):
    1. If option.selected is true, then set selectedShippingOption to option.id.
3. Set details.shippingOptions to options.
Let serializedModifierData be an empty list.
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. Let value be modifier.total.amount.value.
      2. If value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
      3. If the first character of value is U+002D HYPHEN-MINUS, then throw a TypeError, optionally informing the developer that the value can't be negative.
    2. If the additionalDisplayItems member of modifier is present, then for each item of modifier.additionalDisplayItems:
      1. Let value be item.amount.value.
      2. If value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
    3. Let serializedData be the result of JSON-serializing modifier.data into a string, if the data member of modifier is present, or null if it is not. 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.
Let request be a new PaymentRequest.
Set request.[[options]] to options.
Set request.[[state]] to "created".
Set request.[[updating]] to false.
Set request.[[details]] to details.
Set request.[[serializedModifierData]] to serializedModifierData.
Set request.[[serializedMethodData]] to serializedMethodData.
Set the value of request's shippingOption attribute to selectedShippingOption.
Set the value of the shippingAddress attribute on request to null.
Set the value of the shippingType attribute on request to null.
If options.requestShipping is set to true, then set the value of the shippingType attribute on request to options.shippingType. If options.shippingType is not a valid PaymentShippingType value then set the value of the shippingType attribute on request to "shipping".

Note

This behavior allows a page to detect if it supplied an unsupported shipping type. This will be important if new shipping types are added to a future version of this specification but a page is run in a user agent supporting an earlier version.
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 the page 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.

The show() method MUST act as follows:

Let request be the PaymentRequest object on which the method is called.
If the value of request.[[state]] is not " created" then throw an "InvalidStateError" DOMException.
Set the value of request.[[state]] to " interactive".
Let acceptPromise be a new Promise.
Set acceptPromise in request.[[acceptPromise]].
Optionally:
1. Reject acceptPromise with an "AbortError" DOMException.
2. Set request.[[state]] to "closed".
3. Abort this algorithm.
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.
Return acceptPromise and perform the remaining steps in parallel.
For each paymentMethod in request.[[serializedMethodData]]:
1. Consult the appropriate payment apps to see if they support any of the payment method identifiers given by the first element of the paymentMethod tuple, passing along the data string given by the second element of the tuple in order to help them determine their support.
If this consultation produced no supported method of paying, then reject acceptPromise with a "NotSupportedError" DOMException, and abort this algorithm.
Otherwise, show a user interface to allow the user to interact with the payment request process, using those payment apps and payment methods which the above step identified as feasible. The user agent MAY show payment methods in the order given by supportedMethods, but SHOULD prioritize the preference of the user when presenting payment methods and applications.

The payment app should be sent the appropriate data from request in order to guide the user through the payment process. This includes the various attributes and internal slots of request.

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.

3.4 `abort()` method

Note

The abort() method is called if the web page 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, a web page 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.

The abort() method MUST act as follows:

Let request be the PaymentRequest object on which the method is called.
If the value of request.[[state]] is not " interactive" then throw an "InvalidStateError" DOMException.
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel.
Try to abort the current user interaction and close down any remaining user interface.
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 "QuotaExceededError" DOMException, at its discretion.

The canMakePayment() method MUST act as follows:

Let request be the PaymentRequest object on which the method was called.
If request.[[state]] is not "created", then return a promise rejected with an "InvalidStateError" DOMException.
Optionally, at the user agent's discretion, return a promise rejected with a "QuotaExceededError" 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.
Let promise be a new Promise.
Return promise, and perform the remaining steps in parallel.
For each methodData in request.[[serializedMethodData]]:
1. If methodData.supportedMethods contains a payment method identifier of a payment method that the user agent supports, resolve promise with true, and abort this algorithm.
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 `onshippingaddresschange` attribute

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

3.8 `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.9 `onshippingoptionchange` attribute

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

3.10 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: Fig. 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 sequence<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.

The following members are part of the PaymentMethodData dictionary:

supportedMethods member: supportedMethods is a required sequence of strings containing payment method identifiers for payment methods that the merchant web site accepts.
data member: data is an object that provides optional information that might be needed by the supported payment methods. If supplied, it will be JSON-serialized.

5. `PaymentCurrencyAmount` dictionary

dictionary PaymentCurrencyAmount {
    required DOMString currency;
    required DOMString value;
             DOMString currencySystem = "urn:iso:std:iso:4217";
};

A PaymentCurrencyAmount dictionary is used to supply monetary amounts.

currencySystem: 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: A string containing a currency identifier. The value of currency can be any string that is valid within the currency system indicated by currencySystem.
value: A valid decimal monetary value containing a monetary amount.

The following example shows how to represent US$55.00.

Example 5

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

6. `PaymentDetailsBase` dictionary

dictionary PaymentDetailsBase {
    sequence<PaymentItem>            displayItems;
    sequence<PaymentShippingOption>  shippingOptions;
    sequence<PaymentDetailsModifier> modifiers;
};

The following members are part of the PaymentDetailsBase dictionary:

displayItems

This sequence of PaymentItem dictionaries contains line items for the payment request that the user agent MAY display. For example, it might include details of products or breakdown of tax and shipping. It is optional to provide this information.

Note

It is the developer's responsibility to verify that the total amount is the sum of these items.

shippingOptions

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

If the sequence is empty, then this indicates that the merchant cannot ship to the current shippingAddress.

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. Authors SHOULD NOT set selected to true on more than one item. If more than one item in the sequence has selected set to true, then user agents MUST select the last one in the sequence.

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

Note

If the sequence has an item with the selected member set to true, then authors are responsible for ensuring that the total member includes the cost of the shipping option. This is because no shippingoptionchange event will be fired for this option unless the user selects an alternative option first.

modifiers

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

7. `PaymentDetailsInit` dictionary

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

Note

The PaymentDetailsInit dictionary is used in the construction of the payment request.

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

id: id is a free-form identifier for this payment request.

Note

If an id member is not present, then the user agent will generate a unique identifier for the payment request during construction.
total: This PaymentItem contains the non-negative total amount of the payment request.

Note

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

8. `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: 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. For example, this might commonly be used to explain why goods cannot be shipped to the chosen shipping address.
total: This PaymentItem contains the non-negative total amount.

Note

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

9. `PaymentDetailsModifier` dictionary

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

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

supportedMethods: The supportedMethods member contains a sequence of payment method identifiers. The remaining members in the PaymentDetailsModifier apply only if the user selects a payment method included in this sequence.
total: This PaymentItem value overrides the total member in the PaymentDetailsInit dictionary for the payment method identifiers in the supportedMethods member.
additionalDisplayItems: This 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: data is an object that provides optional information that might be needed by the supported payment methods. If supplied, it will be JSON-serialized.

10. `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.

11. `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: This boolean value 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: This boolean value 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: This boolean value 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: This boolean value 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 an online-only electronic purchase transaction.
shippingType: 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 may be used to 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.

12. `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: This is a human-readable description of the item. The user agent may display this to the user.
amount: A PaymentCurrencyAmount containing the monetary amount for the item.
pending: When set to true this flag 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.

13. `PaymentAddress` interface

[SecureContext]
interface PaymentAddress {
    serializer = {attribute};
    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;
};

13.1 `serializer`

Each attribute is converted to serialized values as per [WEBIDL-LS].

13.2 `country` attribute

This is the [CLDR] (Common Locale Data Repository) region code. For example, US, GB, CN, or JP.

13.3 `addressLine` attribute

This is 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.

13.4 `region` attribute

This is the top level administrative subdivision of the country. For example, this can be a state, a province, an oblast, or a prefecture.

13.5 `city` attribute

This is the city/town portion of the address.

13.6 `dependentLocality` attribute

This is the dependent locality or sublocality within a city. For example, used for neighborhoods, boroughs, districts, or UK dependent localities.

13.7 `postalCode` attribute

This is the postal code or ZIP code, also known as PIN code in India.

13.8 `sortingCode` attribute

This is the sorting code as used in, for example, France.

13.9 `languageCode` attribute

This is the BCP-47 language code for the address. It's used to determine the field separators and the order of fields when formatting the address for display.

13.10 `organization` attribute

This is the organization, firm, company, or institution at this address.

13.11 `recipient` attribute

This is 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.

13.12 `phone` attribute

This is the phone number of the recipient or contact person.

14. `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. A web page can provide the user with one or more shipping options by calling the updateWith() method in response to a change event.

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

15. `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 web page did not indicate success or failure and the user agent SHOULD NOT display UI indicating success or failure.

16. `PaymentResponse` interface

[SecureContext]
interface PaymentResponse {
    serializer = {attribute};

    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.

16.1 `serializer`

Each attribute is converted to serialized values as per [WEBIDL-LS].

16.2 `methodName` attribute

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

16.3 `details` attribute

An object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer. This data is returned by the payment method specific code that satisfies the payment request.

16.4 `shippingAddress` attribute

If the requestShipping flag 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.

16.5 `shippingOption` attribute

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

16.6 `payerName` attribute

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

16.7 `payerEmail` attribute

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

16.8 `payerPhone` attribute

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

16.9 `requestId` attribute

The corresponding payment request id that spawned this payment response.

16.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 transaction 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 page but before the page 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 page never calls complete() then the user interface is blocked.

For this reason, implementations MAY impose a timeout for the page 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:

Let promise be a new Promise.
If the value of the internal slot [[completeCalled]] is true, then throw an "InvalidStateError" DOMException.
Set the value of the internal slot [[completeCalled]] to true.
Return promise and perform the remaining steps in parallel.
Close down any remaining user interface. The user agent MAY use the value result to influence the user experience. User agents SHOULD treat unrecognized result values as the value "unknown".
Resolve promise with undefined.

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

18. Events

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

18.2 `PaymentRequestUpdateEvent` interface

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

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

If the web page wishes to update the payment request then it should call updateWith() and provide a PaymentDetailsUpdate dictionary, or a promise for one, containing changed values that the user agent SHOULD present to the user.

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

18.2.1 `updateWith()` method

Note

The updateWith(detailsPromise) method MUST act as follows:

Let event be this PaymentRequestUpdateEvent instance.
Let target be the value of event's target attribute.
If target is not a PaymentRequest object, then throw a TypeError.
If the dispatch flag is unset, then throw an " InvalidStateError" DOMException.
If event.[[waitForUpdate]] is true, then throw an "InvalidStateError" DOMException.
If target.[[state]] is not " interactive", then throw an " InvalidStateError" DOMException.
If target.[[updating]] is true, then throw an "InvalidStateError" DOMException.
Set event's stop propagation flag and stop immediate propagation flag.
Set event.[[waitForUpdate]] to true.
Set target.[[updating]] to true.
The user agent SHOULD disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the web page has made changes required by the change. The web page MUST settle the detailsPromise to indicate that the payment request is valid again.
The user agent SHOULD disable any part of the user interface that could cause another update event to be fired. Only one update may be processed at a time.
Return from the method and perform the remaining steps in parallel.

The remaining 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.
Upon rejection of detailsPromise:
1. Abort the current user interaction and close down any remaining user interface.
2. Set target.[[state]] to "closed".
3. Reject the promise target.[[acceptPromise]] with an " AbortError" DOMException.
Note

If the promise detailsPromise is rejected then this is a fatal error for the payment request. This would potentially leave the payment request in an inconsistent state since the web page hasn't successfully handled the change event. Consequently, if detailsPromise is rejected then the payment request is aborted.
User agents might show an error message to the user when this occurs.
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 these substeps, and optionally show an error message to the user.
2. If the total member of details is present, then:
  1. Let value be details.total.amount.value.
  2. If value is a valid decimal monetary value and the first character of value is not U+002D HYPHEN-MINUS, then copy details.total to the total member of target.[[details]]. (Negative total amounts are ignored.)
3. If the displayItems member of details is present, then:
  1. If every PaymentItem in details.displayItems has an amount.value containing a valid decimal monetary value, then copy details.displayItems to the displayItems member of target.[[details]].
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. If the total member of modifier is present and member.total.amount.value is not a valid decimal monetary value, then set modifiers to an empty sequence and serializedModifierData to an empty list, and jump to the step labeled copy modifiers below.
    2. If the additionalDisplayItems member of modifier is present, then for each PaymentItem item in modifier.additionalDisplayItems:
      1. Let amountValue be item.amount.value.
      2. If amountValue is not a valid decimal monetary value, then set modifiers to an empty sequence and serializedModifierData to an empty list, and jump to the step labeled copy modifiers below.
    3. Let serializedData be the result of JSON-serializing modifier.data into a string, if the data member of modifier is present, or null if it is not. If JSON-serializing throws an exception, then set modifiers to an empty sequence and serializedModifierData to an empty list, and jump to the step labeled copy modifiers below.
    4. Add serializedData to serializedModifierData.
    5. Remove the data member of modifier, if it is present.
  4. Copy modifiers: Set target.[[details]].modifiers to modifiers, and set target.[[serializedModifierData]] to serializedModifierData.
5. If the shippingOptions member of details is present, and target.[[options]].requestShipping is true, then:
  1. Let options be details.shippingOptions.
  2. Let seenIDs be an empty list.
  3. For each option in options:
    1. If option.amount.value is not a valid decimal monetary value, then set options to the empty sequence and break.
    2. If seenIDs contains option.id, then set options to an empty sequence and break.
    3. Append option.id to seenIDs.
  4. For each option in options (which may have been reset to the empty sequence in the previous step):
    1. If option.selected is true, then set selectedShippingOption to option.id.
  5. Copy options to the shippingOptions member of target.[[details]].
6. If the error member of details is present, then the user agent should update the user interface to display the error message contained in error.
In either case, run the following steps, after either the upon rejection or upon fulfillment steps have concluded:
1. Set event.[[waitForUpdate]] to false.
2. Set target.[[updating]] to false.
3. The user agent should update the user interface based on any changed values in target. The user agent SHOULD re-enable user interface elements that might have been disabled in the steps above if appropriate.

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

18.2.3 `PaymentRequestUpdateEventInit` dictionary

dictionary PaymentRequestUpdateEventInit : EventInit {
};

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

19.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:

Let request be the PaymentRequest object that the user is interacting with.
Let name be "shippingaddresschange".
Queue a task on the user interaction task source to run the following steps:
1. Set the shippingAddress attribute on request to the shipping address provided by the user.
2. Run the PaymentRequest updated algorithm with request and name.

19.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:

Let request be the PaymentRequest object that the user is interacting with.
Let name be shippingoptionchange.
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.

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

It MUST run the following steps:

If the request.[[updating]] is true, then terminate this algorithm and take no further action. Only one update may take place at a time. This should never occur.
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.
Let event be a new PaymentRequestUpdateEvent.
Fire an event named name at request using PaymentRequestUpdateEvent.

19.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 run the following steps:

Let request be the PaymentRequest object that the user is interacting with.
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.
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.
If the requestShipping value of request.[[options]] is true, then if the shippingAddress attribute of request is null or if the shippingOption attribute of request is null, then terminate this algorithm and take no further action. This should never occur.
Let response be a new PaymentResponse.
Set the requestId attribute value of response to the value of request.[[details]].id.
Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
Set the details attribute value of response to an object containing the payment method specific message that will be used by the merchant to process the transaction. The format of this response will be defined for each payment method.
If the requestShipping value of request.[[options]] is true, then set the shippingAddress attribute of response to the value of the shippingAddress attribute of request. Otherwise, set it to null.
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.
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.
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.
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.
Set response.[[completeCalled]] to false.
Set request.[[state]] to "closed".
Resolve the pending promise request.[[acceptPromise]] with response.

19.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 run the following steps:

Let request be the PaymentRequest object that the user is interacting with.
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.
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.
Queue a task on the user interaction task source to perform the following steps:
1. Set request.[[state]] to "closed".
2. Reject the promise request.[[acceptPromise]] with an " AbortError" DOMException.

20.1 Encryption of data fields

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.

21.1 Exposing user information

The user agent MUST NOT share information about the user to the web page (such as the shipping address) without user consent.

21.2 Exposing available payment methods

A page might try to call the payment request API repeatedly with only one payment method identifier to try to determine what payment methods a user agent has installed. There may be legitimate scenarios for calling repeatedly (for example, to control the order of payment method selection). The fact that a successful match to a payment method causes a user interface to be displayed mitigates the disclosure risk. Implementations may also require a user action to initiate a payment request or they may choose to rate limit the calls to the API to prevent too many repeated calls.

22. Dependencies

This specification relies on several other underlying specifications.

Payment Method Identifiers

The term payment method identifier is defined by [METHOD-IDENTIFIERS].

HTML

The following are defined by [HTML]:

ECMA-262 6th Edition, The ECMAScript 2015 Language Specification

The terms Promise, internal slot,


          TypeError

, and JSON.stringify are defined by [ECMA-262-2015].

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 and the terms fire an event, dispatch flag, stop propagation flag, 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-LS]. 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-LS].

DOMException and the following DOMException types from [WEBIDL-LS] are used:

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

B.1 Normative references

[CLDR]: Unicode Common Locale Data Repository. Unicode Consortium. URL: http://cldr.unicode.org/
[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-262-2015]: ECMA-262 6th Edition, The ECMAScript 2015 Language Specification. Allen Wirfs-Brock. Ecma International. June 2015. Standard. URL: http://www.ecma-international.org/ecma-262/6.0/index.html
[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/
[METHOD-IDENTIFIERS]: Payment Method Identifiers. Adrian Bateman; Zach Koch; Roy McElmurry.W3C Working Draft. 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-LS]: Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

B.2 Informative references

[ISO4217]: Currency codes - ISO 4217. ISO. 2015. International Standard. URL: http://www.iso.org/iso/home/standards/currency_codes.htm
[WEBIDL]: Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/

Abstract

Status of This Document

1. Introduction

1.1 Goals

1.1.1 Out of scope

2. Definitions

3. PaymentRequest interface

3.1 Constructor

3.2 id attribute

3.3 show() method

3.4 abort() method

3.5 canMakePayment() method

3.6 shippingAddress attribute

3.7 onshippingaddresschange attribute

3.8 shippingOption attribute

3.9 onshippingoptionchange attribute

3.10 Internal Slots

4. PaymentMethodData dictionary

5. PaymentCurrencyAmount dictionary

6. PaymentDetailsBase dictionary

7. PaymentDetailsInit dictionary

8. PaymentDetailsUpdate dictionary

9. PaymentDetailsModifier dictionary

10. PaymentShippingType enum

11. PaymentOptions dictionary

12. PaymentItem dictionary

13. PaymentAddress interface

13.1 serializer

13.2 country attribute

13.3 addressLine attribute

13.4 region attribute

13.5 city attribute

13.6 dependentLocality attribute

13.7 postalCode attribute

13.8 sortingCode attribute

13.9 languageCode attribute

13.10 organization attribute

13.11 recipient attribute

13.12 phone attribute

14. PaymentShippingOption dictionary

15. PaymentComplete enum

16. PaymentResponse interface

16.1 serializer

16.2 methodName attribute

16.3 details attribute

16.4 shippingAddress attribute

16.5 shippingOption attribute

16.6 payerName attribute

16.7 payerEmail attribute

16.8 payerPhone attribute

16.9 requestId attribute

16.10 complete() method

16.11 Internal Slots

17. PaymentRequest and iframe elements

18. Events

18.1 Summary

18.2 PaymentRequestUpdateEvent interface

18.2.1 updateWith() method

18.2.2 Internal Slots

18.2.3 PaymentRequestUpdateEventInit dictionary

19. Algorithms

19.1 Shipping address changed algorithm

19.2 Shipping option changed algorithm

19.3 PaymentRequest updated algorithm

19.4 User accepts the payment request algorithm

19.5 User aborts the payment request algorithm

20. Security Considerations

20.1 Encryption of data fields

21. Privacy Considerations

21.1 Exposing user information

21.2 Exposing available payment methods

22. Dependencies

23. Conformance

A. IDL Index

B. References

B.1 Normative references

B.2 Informative references

3. `PaymentRequest` interface

3.2 `id` attribute

3.3 `show()` method

3.4 `abort()` method

3.5 `canMakePayment()` method

3.6 `shippingAddress` attribute

3.7 `onshippingaddresschange` attribute

3.8 `shippingOption` attribute

3.9 `onshippingoptionchange` attribute

4. `PaymentMethodData` dictionary

5. `PaymentCurrencyAmount` dictionary

6. `PaymentDetailsBase` dictionary

7. `PaymentDetailsInit` dictionary

8. `PaymentDetailsUpdate` dictionary

9. `PaymentDetailsModifier` dictionary

10. `PaymentShippingType` enum

11. `PaymentOptions` dictionary

12. `PaymentItem` dictionary

13. `PaymentAddress` interface

13.1 `serializer`

13.2 `country` attribute

13.3 `addressLine` attribute

13.4 `region` attribute

13.5 `city` attribute

13.6 `dependentLocality` attribute

13.7 `postalCode` attribute

13.8 `sortingCode` attribute

13.9 `languageCode` attribute

13.10 `organization` attribute

13.11 `recipient` attribute

13.12 `phone` attribute

14. `PaymentShippingOption` dictionary

15. `PaymentComplete` enum

16. `PaymentResponse` interface

16.1 `serializer`

16.2 `methodName` attribute

16.3 `details` attribute

16.4 `shippingAddress` attribute

16.5 `shippingOption` attribute

16.6 `payerName` attribute

16.7 `payerEmail` attribute

16.8 `payerPhone` attribute

16.9 `requestId` attribute

16.10 `complete()` method

17. PaymentRequest and `iframe` elements

18.2 `PaymentRequestUpdateEvent` interface

18.2.1 `updateWith()` method

18.2.3 `PaymentRequestUpdateEventInit` dictionary