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)
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 ShippingAddress? 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 [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;
        };
      

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.

CurrencyAmount

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

A CurrencyAmount dictionary is used to supply monetary amounts. The following fields MUST be supplied for a CurrencyAmount 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 and user agents MUST not attempt to validate this string.

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

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 the sequence only contains one item, then this is the shipping option that will be used and shippingOption will be set to the id of this option without running the shipping option changed algorithm.

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

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

There is an open issue about whether it should be possible to provide a different amounts depending upon the payment method.

ShippingAddress interface

        interface ShippingAddress {
          readonly attribute DOMString regionCode;
          readonly attribute FrozenArray<DOMString> addressLine;
          readonly attribute DOMString administrativeArea;
          readonly attribute DOMString locality;
          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;
        };
      

regionCode

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.

administrativeArea

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

locality

This is the city/town portion of the address.

dependentLocality

This is the dependent locality or sublocality. 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.

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.

ShippingOption interface

        dictionary ShippingOption {
          required string id;
          required string label;
          required CurrencyAmount amount;
        };
      

The ShippingOption 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 ShippingOption. 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 CurrencyAmount containing the monetary amount for the item.

PaymentResponse interface

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

        interface PaymentResponse {
          readonly attribute DOMString methodName;
          readonly attribute object details;
          readonly attribute ShippingAddress? shippingAddress;
          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.

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.