This specification describes a web API to allow merchants (i.e. web sites selling physical or digital goods) to easily accept payments from different payment methods with minimal integration. User agents (e.g., browsers) will facilitate the payment flow between merchant and user.

The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

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

This specification defines one class of products:

Conforming user agent

A user agent MUST behave as described in this specification in order to be considered conformant. In this specification, user agent means a Web browser or other interactive user agent as defined in [[!HTML5]].

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.

A conforming Payment Request API user agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [[!WEBIDL]]

Dependencies

This specification relies on several other underlying specifications.

Payment Request Architecture

The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [[PAYMENT-ARCH]].

Payment Method Identifiers

The term Payment Method Identifier is defined by the Payment Method Identifiers specification [[!METHOD-IDENTIFIERS]].

HTML5

The terms global object, queue a task, browsing context, and top-level browsing context are defined by [[!HTML5]].

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

The terms Promise, internal slot, TypeError, JSON.stringify, and JSON.parse are defined by [[!ECMA-262-2015]].

This document uses the format object@[[\slotname]] to mean the internal slot [[\slotname]] of the object object.

The term JSON-serializable object used in this specification means an object that can be serialized to a string using JSON.stringify and later deserialized back to an object using JSON.parse with no loss of data.

DOM4

The Event type and the terms fire an event, dispatch flag, stop propagation flag, and stop immediate propagation flag are defined by [[!DOM4]].

DOMException and the following DOMException types from [[!DOM4]] are used:

Type	Message (optional)
AbortError	The payment request was aborted
InvalidStateError	The object is in an invalid state
NotSupportedError	The payment method was not supported
SecurityError	The operation is only supported in a secure context

WebIDL

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

The term extended attribute is defined by [[!WEBIDL]].

Secure Contexts

The term secure context is defined by the Secure Contexts specification [[!POWERFUL-FEATURES]].

PaymentRequest interface

        [Constructor(sequence<PaymentMethodData> methodData, PaymentDetails details, optional PaymentOptions options),
        SecureContext]
        interface PaymentRequest : EventTarget {
          Promise<PaymentResponse> show();
          Promise<void> abort();

          readonly attribute PaymentAddress? shippingAddress;
          readonly attribute DOMString? shippingOption;

          /* Supports "shippingaddresschange" event */
          attribute EventHandler onshippingaddresschange;

          /* Supports "shippingoptionchange" event */
          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 and shippingOption attributes are populated during processing if the requestShipping flag is set.

The [SecureContext] extended attribute means that the PaymentRequest is only exposed within a secure context and won't be accessible elsewhere.

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

        var payment = new PaymentRequest(methodData, details, options);
        payment.addEventListener("shippingaddresschange", function (changeEvent) {
            // Process shipping address change
        });

        payment.show().then(function(paymentResponse) {
          // Process paymentResponse
          // paymentResponse.methodName contains the selected payment method
          // paymentResponse.details contains a payment method specific response
          paymentResponse.complete("success");
        }).catch(function(err) {
          console.error("Uh oh, something bad happened", err.message);
        });
      

            [
              {
                supportedMethods: ["visa","bitcoin"]
              },
              {
                supportedMethods: ["bobpay.com"],
                data: {
                  merchantIdentifier: "XXXX",
                  bobPaySpecificField: true
                }
              }
            ]
          

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

            {
              requestShipping: true
            }
          

State transitions

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

PaymentMethodData dictionary

        dictionary PaymentMethodData {
          required sequence<DOMString> supportedMethods;
          object data;
          sequence<RecommendedPaymentApp> recommendedApps;
        };
      

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 fields are part of the PaymentMethodData dictionary:

supportedMethods

supportedMethods is a required sequence of strings containing payment method identifiers for payment methods that the merchant web site accepts.

data

data is a JSON-serializable object that provides optional information that might be needed by the supported payment methods.

recommendedApps

recommendedApps is a RecommendedPaymentApp dictionary that provides the user agent with enough information to invoke the app.

RecommendedPaymentApp

        dictionary RecommendedPaymentApp {
          required URLString request_url;
          required DOMString label;
          DOMString icon;
        };
      

A RecommendedPaymentApp is used to supply the user agent with enough information to invoke the payment app with or without prior registration. The following fields are part of RecommendedPaymentApp:

request_url

request_url is a string that represents the request URL, which is the URL that accepts payment request messages via HTTP POST.

label

label is a string that represents the lable for this option as it is usually displayed to the user when selecting a payment app.

icon

PaymentCurrencyAmount

dictionary PaymentCurrencyAmount {
  required DOMString currency;
  required DOMString value;
};
      

A PaymentCurrencyAmount dictionary is used to supply monetary amounts. The following fields MUST be supplied for a PaymentCurrencyAmount to be valid:

currency

currency is a string containing a currency identifier. The most common identifiers are three-letter alphabetic codes as defined by [[!ISO4217]] (for example, "USD" for US Dollars) however any string is considered valid.

value

A string containing the decimal monetary value. If a decimal separator is needed, then the string MUST use a single U+002E FULL STOP character as the decimal separator. The string MUST begin with a single U+002D HYPHEN-MINUS character if the value is negative. All other characters must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

The string should match the regular expression ^-?[0-9]+(\.[0-9]+)?$.

The following example shows how to represent US$55.00.

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

PaymentDetails dictionary

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

The PaymentDetails dictionary is passed to the PaymentRequest constructor and provides information about the requested transaction. The PaymentDetails dictionary is also used to update the payment request using updateWith.

The following fields are part of the PaymentDetails dictionary:

total

This PaymentItem contains the total amount of the payment request.

total MUST be a non-negative value. This means that the total.amount.value field MUST NOT begin with a U+002D HYPHEN-MINUS character.

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.

The user agent MAY validate that the total amount is the sum of these items, but it is the responsibility of the calling code to ensure that.

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 field 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 field is only used if the PaymentRequest was constructed with PaymentOptions requestShipping set to true.

If the sequence has an item with the selected field set to true, then authors SHOULD ensure that the total field 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.

PaymentDetailsModifier dictionary

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

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

supportedMethods

The supportedMethods field contains a sequence of payment method identifiers. The remaining fields in the PaymentDetailsModifier apply only if the user selects a payment method included in this sequence.

total

This PaymentItem value overrides the total field in the PaymentDetails dictionary for the payment method identifiers in the supportedMethods field.

additionalDisplayItems

This sequence of PaymentItem dictionaries provides additional display items that are appended to the displayItems field in the PaymentDetails dictionary for the payment method identifiers in the supportedMethods field. This field 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.

The user agent MAY validate that the total amount is the sum of the displayItems and the additionalDisplayItems, but it is the responsibility of the calling code to ensure that.

PaymentOptions dictionary

dictionary PaymentOptions {
  boolean requestPayerEmail = false;
  boolean requestPayerPhone = false;
  boolean requestShipping = false;
};
      

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

The following fields MAY be passed to the PaymentRequest constructor:

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.

PaymentItem dictionary

        dictionary PaymentItem {
          required DOMString label;
          required PaymentCurrencyAmount amount;
        };
      

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

The following fields MUST be included in a PaymentItem for it to be valid:

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.

There is an open issue about whether it should be possible to provide a PaymentItem with amounts in more than once currency.

PaymentAddress interface

        interface PaymentAddress {
          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 careOf;
          readonly attribute DOMString phone;
        };
      

country

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

addressLine

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.

region

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

city

This is the city/town portion of the address.

dependentLocality

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

postalCode

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

sortingCode

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

languageCode

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.

organization

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

recipient

This is the name of the recipient or contact person.

careOf

This is the name of an intermediary party or entity responsible for transferring packages between the postal service and the recipient.

phone

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

If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then the user agent will populate the shippingAddress field of the PaymentRequest and ultimately the PaymentResponse object with the user's selected shipping address after the user has accepted the payment.

PaymentShippingOption dictionary

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

The PaymentShippingOption dictionary has fields 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.

The following fields MUST be included in a PaymentItem for it to be valid:

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.

PaymentResponse interface

        enum PaymentComplete { "success", "fail", "" };

        interface PaymentResponse {
          readonly attribute DOMString methodName;
          readonly attribute object details;
          readonly attribute PaymentAddress? shippingAddress;
          readonly attribute DOMString?      shippingOption;
          readonly attribute DOMString? payerEmail;
          readonly attribute DOMString? payerPhone;

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

A PaymentResponse is returned when a user has selected a payment method and approved a payment request. It contains the following fields:

methodName

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

details

A JSON-serializable object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer. This data is returned by the payment app that satisfies the payment request.

shippingAddress

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.

shippingOption

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.

payerEmail

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.

payerPhone

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.

Events

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

dictionary PaymentRequestUpdateEventInit : EventInit {
};
        

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.