Payment Request API

Abstract

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

2. Examples of usage

This section is non-normative.

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

The methodData: A sequence of PaymentMethodDatas that represents the payment methods that the site supports (e.g., "we support card-based payments, but only Visa and MasterCard credit cards.").
The details: The details of the transaction, as a PaymentDetailsInit dictionary. This includes total cost, and optionally a list of goods or services being purchased. Additionally, it can optionally include "modifiers" to how payments are made. For example, "if you pay with a card belonging to network X, it incurs a US$3.00 processing fee".

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

2.1 Declaring multiple ways of paying

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

Example 1: The `methodData` argument

const methodData = [
  {
    supportedMethods: "https://example.com/payitforward",
    data: {
      payItForwardField: "ABC",
    },
  },
  {
    supportedMethods: "https://example.com/bobpay",
    data: {
      merchantIdentifier: "XXXX",
      bobPaySpecificField: true,
    },
  },
];

2.2 Describing what is being paid for

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

Example 2: The `details` argument

const details = {
  id: "super-store-order-123-12312",
  displayItems: [
    {
      label: "Sub-total",
      amount: { currency: "GBP", value: "55.00" },
    },
    {
      label: "Value-Added Tax (VAT)",
      amount: { currency: "GBP", value: "5.00" },
    },
    {
      label: "Standard shipping",
      amount: { currency: "GBP", value: "5.00" },
    },
  ],
  total: {
    label: "Total due",
    // The total is GBP£65.00 here because we need to
    // add tax and shipping.
    amount: { currency: "GBP", value: "65.00" },
  },
};

2.3 Conditional modifications to payment request

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

Example 3: Modifying payment request based on card type

// Certain cards incur a $3.00 processing fee.
const cardFee = {
  label: "Card processing fee",
  amount: { currency: "AUD", value: "3.00" },
};

// Modifiers apply when the user chooses to pay with
// a card.
const modifiers = [
  {
    additionalDisplayItems: [cardFee],
    supportedMethods: "https://example.com/cardpay",
    total: {
      label: "Total due",
      amount: { currency: "AUD", value: "68.00" },
    },
    data: {
      supportedNetworks: networks,
    },
  },
];
Object.assign(details, { modifiers });

2.4 Constructing a `PaymentRequest`

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

Example 4: Constructing a `PaymentRequest`

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}
async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong...
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

2.5 POSTing payment response back to a server

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

Example 5: POSTing with `fetch()`

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

2.6 Using with cross-origin iframes

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

Example 6: Using Payment Request API with cross-origin iframes

<iframe
  src="https://cross-origin.example"
  allow="payment">
</iframe>

If the iframe will be navigated across multiple origins that support the Payment Request API, then one can set allow to "payment *". The Permissions Policy specification provides further details and examples.

3. `PaymentRequest` interface

WebIDL[SecureContext, Exposed=Window]
interface PaymentRequest : EventTarget {
  constructor(
    sequence<PaymentMethodData> methodData,
    PaymentDetailsInit details
  );
  [NewObject]
  Promise<PaymentResponse> show(optional Promise<PaymentDetailsUpdate> detailsPromise);
  [NewObject]
  Promise<undefined> abort();
  [NewObject]
  Promise<boolean> canMakePayment();

  readonly attribute DOMString id;

  attribute EventHandler onpaymentmethodchange;
};

Note

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

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

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

3.1 Constructor

The PaymentRequest is constructed using the supplied sequence of PaymentMethodData methodData including any payment method specific data, and the PaymentDetailsInit details.

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

If the current settings object's responsible document is not allowed to use the "payment" permission, then throw a "SecurityError" DOMException.
Establish the request's id:
1. If details.id is missing, add an id member to details and set its value to a UUID [RFC4122].
Let serializedMethodData be an empty list.
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. Let seenPMIs be the empty set.
3. For each paymentMethod of methodData:
  1. Run the steps to validate a payment method identifier with paymentMethod.supportedMethods. If it returns false, then throw a RangeError exception. Optionally, inform the developer that the payment method identifier is invalid.
  2. Let pmi be the result of parsing paymentMethod.supportedMethods with basic URL parser:
    1. If failure, set pmi to paymentMethod.supportedMethods.
  3. If seenPMIs contains pmi throw a RangeError DOMException optionally letting the developer this payment method identifier is a duplicate.
  4. Append pmi to seenPMIs.
  5. If the data member of paymentMethod is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing paymentMethod.data into a string. Rethrow any exceptions.
  6. If serializedData is not null, and if required by the specification that defines the paymentMethod.supportedMethods:
    1. Let object be the result of JSON-parsing serializedData.
    2. Convert object to an IDL value of the type specified by the specification that defines the paymentMethod.supportedMethods Rethrow any exceptions.
      
      Note
      This step assures that any IDL type conversion errors are caught as early as possible.
  7. Add the tuple (paymentMethod.supportedMethods, serializedData) to serializedMethodData.
Process the total:
1. Check and canonicalize total amount details.total.amount. Rethrow any exceptions.
If the displayItems member of details is present, then for each item in details.displayItems:
1. Check and canonicalize amount item.amount. Rethrow any exceptions.
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. Check and canonicalize total amount modifier.total.amount. Rethrow any exceptions.
    2. If the additionalDisplayItems member of modifier is present, then for each item of modifier.additionalDisplayItems:
      1. Check and canonicalize amount item.amount. Rethrow any exceptions.
    3. If the data member of modifier is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing modifier.data into a string. Rethrow any exceptions.
    4. Add the tuple (modifier.supportedMethods, serializedData) to serializedModifierData.
    5. Remove the data member of modifier, if it is present.
3. Set details.modifiers to modifiers.
Let request be a new PaymentRequest.
Set request.[[handler]] to null.
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 request.[[response]] to null.
Return request.

3.2 `id` attribute

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

Note

For auditing and reconciliation purposes, a merchant can associate a unique identifier for each transaction with the id attribute.

3.3 `show()` method

Note

The show() method is called when a developer wants to begin user interaction for the payment request. The show() method returns a Promise that will be resolved when the user accepts the payment request. Some kind of user interface will be presented to the user to facilitate the payment request after the show() method returns.

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

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

Let request be this.
If the relevant global object of request does not have transient activation:
1. Return a promise rejected with with a "SecurityError" DOMException.
Consume user activation of the relevant global object.
Let document be request's relevant global object's associated Document.
If document is not fully active, then return a promise rejected with an "AbortError" DOMException.
Optionally, if the user agent wishes to disallow the call to show() to protect the user, then return a promise rejected with a "SecurityError" DOMException. For example, the user agent may limit the rate at which a page can call show(), as described in section § 14. Privacy and Security Considerations.
If request.[[state]] is not "created" then return a promise rejected with an "InvalidStateError" DOMException.
If the user agent's payment request is showing boolean is true, then:
1. Set request.[[state]] to "closed".
2. Return a promise rejected with an "AbortError" DOMException.
Set request.[[state]] to "interactive".
Let acceptPromise be a new promise.
Set request.[[acceptPromise]] to acceptPromise.
Optionally:
1. Reject acceptPromise with an "AbortError" DOMException.
2. Set request.[[state]] to "closed".
3. Return acceptPromise.
Note
This allows the user agent to act as if the user had immediately aborted the payment request, at its discretion. For example, in "private browsing" modes or similar, user agents might take advantage of this step.
Set request's payment-relevant browsing context's payment request is showing boolean to true.
Return acceptPromise and perform the remaining steps in parallel.
Let handlers be an empty list.
For each paymentMethod tuple in request.[[serializedMethodData]]:
1. Let identifier be the first element in the paymentMethod tuple.
2. Let data be the result of JSON-parsing the second element in the paymentMethod tuple.
3. If required by the specification that defines the identifier, then convert data to an IDL value of the type specified there. Otherwise, convert to object.
4. If conversion results in an exception error:
  1. Set request.[[state]] to "closed".
  2. Reject acceptPromise with error.
  3. Set request's payment-relevant browsing context's payment request is showing boolean to false.
  4. Terminate this algorithm.
5. Let registeredHandlers be a list of registered payment handlers for the payment method identifier.
6. For each handler in registeredHandlers:
  1. Let canMakePayment be the result of running handler's steps to check if a payment can be made with data.
  2. If canMakePayment is true, then append handler to handlers.
If handlers is empty, then:
1. Set request.[[state]] to "closed".
2. Reject acceptPromise with "NotSupportedError" DOMException.
3. Set request's payment-relevant browsing context's payment request is showing boolean to false.
4. Terminate this algorithm.
Present a user interface that will allow the user to interact with the handlers. The user agent SHOULD prioritize the user's preference when presenting payment methods. The user interface SHOULD be presented using the language and locale-based formatting that matches the document's document element's language, if any, or an appropriate fallback if that is not available.

Note: Localization of the payments user interface

The API does not currently provide a way for developers to specify the language and base direction in which the payment sheet is presented to end users. Instead, the API relies on localization information inherited from the document. The working group is considering support for requesting specific localization of the user interface and of individual PaymentItems and user-facing error messages in a future version of this API.
If detailsPromise was passed, then:
1. Run the update a PaymentRequest's details algorithm with detailsPromise, request, and null.
2. Wait for the detailsPromise to settle.
  Note
  Based on how the detailsPromise settles, the update a PaymentRequest's details algorithm determines how the payment UI behaves. That is, upon rejection of the detailsPromise, the payment request aborts. Otherwise, upon fulfillment detailsPromise, the user agent re-enables the payment request UI and the payment flow can continue.
Set request.[[handler]] be the payment handler selected by the end-user.
Let modifiers be an empty list.
For each tuple in [[serializedModifierData]]:
1. If the first element of tuple (a PMI) matches the payment method identifier of request.[[handler]], then append the second element of tuple (the serialized method data) to modifiers.
Pass the converted second element in the paymentMethod tuple and modifiers. Optionally, the user agent SHOULD send the appropriate data from request to the user-selected payment handler in order to guide the user through the payment process. This includes the various attributes and other internal slots of request (some MAY be excluded for privacy reasons where appropriate).

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

This example demonstrates precedence order of [[serializedModifierData]]. The first modifier applies equally to all cards, irrespective of network. The second modifier applies specifically to cards on the "coolcard" network.
```
const details = {
  total: {
    label: "Total due",
    amount: { currency: "USD", value: "65.00" },
  },
};
// All cards incur a $3.00 processing fee.
const cardFee = {
  label: "Card processing fee",
  amount: { currency: "USD", value: "3.00" },
};

// But coolcard incurs a $1.00 processing fee.
const coolCardFee = {
  label: "Coolcard processing fee",
  amount: { currency: "USD", value: "1.00" },
};

// Modifiers apply when the user chooses to pay with
// a credit card.
details.modifiers = [
  // Applies to all cards...
  {
    additionalDisplayItems: [cardFee],
    supportedMethods: "https://example.com/cardpay",
    total: {
      label: "Total due",
      amount: { currency: "USD", value: "53.00" },
    },
    data: {
      supportedNetworks: [], // All networks
    },
  },
  // Applies only to visa cards...
  {
    additionalDisplayItems: [coolCardFee],
    supportedMethods: ""https://example.com/cardpay",
    total: {
      label: "Total due",
      amount: { currency: "USD", value: "51.00" },
    },
    data: {
      supportedNetworks: ["coolcard"], // coolcard network only
    },
  },
];
```
If the modifiers array in the example above was to be reversed (i.e., supportedNetworks: [] was to come last in the modifiers list), then it would take precedence over the "coolcard" modifier even though the coolcard modifier matches cards more specifically. This is because "last one wins".
The acceptPromise will later be resolved or rejected by either the user accepts the payment request algorithm or the user aborts the payment request algorithm, which are triggered through interaction with the user interface.

If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
1. Close down the user interface.
2. Set request's payment-relevant browsing context's payment request is showing boolean to false.

3.4 `abort()` method

Note

The abort() method is called if a developer wishes to tell the user agent to abort the payment request and to tear down any user interface that might be shown. The abort() can only be called after the show() method has been called (see states) and before this instance's [[acceptPromise]] has been resolved. For example, developers might choose to do this if the goods they are selling are only available for a limited amount of time. If the user does not accept the payment request within the allowed time period, then the request will be aborted.

A user agent might not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. In this situation, abort() will reject the returned Promise.

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

The abort() method MUST act as follows:

Let request be this.
If request.[[response]] is not null, and request.[[response]].[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
If the value of request.[[state]] is not "interactive" then return a promise rejected with 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 with the payment handler 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 request.[[state]] to "closed".
3. Reject the promise request.[[acceptPromise]] with an "AbortError" DOMException.
4. Resolve promise with undefined.

3.5 `canMakePayment()` method

Note: canMakePayment()

The canMakePayment() method can be used by the developer to determine if the user agent has support for one of the desired payment methods. See § 14.8 canMakePayment() protections.

A true result from canMakePayment() does not imply that the user has a provisioned instrument ready for payment.

The canMakePayment() method MUST run the can make payment algorithm.

3.6 `onpaymentmethodchange` attribute

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

3.7 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.
[[state]]	The current state of the payment request, which transitions from: "created" The payment request is constructed and has not been presented to the user. "interactive" The payment request is being presented to the user. "closed" The payment request completed. The state transitions are illustrated in the figure below: Figure 1 The constructor sets the initial state to "created". The `show()` method changes the state to "interactive". From there, the `abort()` method or any other error can send the state to "closed"; similarly, the user accepts the payment request algorithm and user aborts the payment request algorithm will change the state to "closed".
[[updating]]	True if there is a pending `updateWith()` call to update the payment request and false otherwise.
[[acceptPromise]]	The pending `Promise` created during `show()` that will be resolved if the user accepts the payment request.
[[response]]	Null, or the `PaymentResponse` instantiated by this `PaymentRequest`.
[[handler]]	The Payment Handler associated with this `PaymentRequest`. Initialized to `null`.

6. Payment details dictionaries

6.1 `PaymentDetailsBase` dictionary

WebIDLdictionary PaymentDetailsBase {
  sequence<PaymentItem> displayItems;
  sequence<PaymentDetailsModifier> modifiers;
};

displayItems member: A sequence of PaymentItem dictionaries contains line items for the payment request that the user agent MAY display.
Note
It is the developer's responsibility, when generating or updating a PaymentRequest, to verify that the total amount is the sum of these items.
modifiers member: A sequence of PaymentDetailsModifier dictionaries that contains modifiers for particular payment method identifiers. For example, it allows you to adjust the total amount based on payment method.

6.2 `PaymentDetailsInit` dictionary

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

Note

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

id member: A free-form identifier for this payment request.
Note
If an id member is not present, then the user agent will generate a unique identifier for the payment request during construction
total member: A PaymentItem containing a non-negative total amount for the payment request.
Note
Algorithms in this specification that accept a PaymentDetailsInit dictionary will throw if the total.amount.value is a negative number.

6.3 `PaymentDetailsUpdate` dictionary

WebIDLdictionary PaymentDetailsUpdate : PaymentDetailsBase {
  PaymentItem total;
  object paymentMethodErrors;
};

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

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

total member: A PaymentItem containing a non-negative amount.
Note
Algorithms in this specification that accept a PaymentDetailsUpdate dictionary will throw if the total.amount.value is a negative number.
paymentMethodErrors member: Payment method specific errors.

10. `PaymentResponse` interface

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

  readonly attribute DOMString requestId;
  readonly attribute DOMString methodName;
  readonly attribute object details;

  [NewObject]
  Promise<undefined> complete(optional PaymentComplete result = "unknown");
  [NewObject]
  Promise<undefined> retry(optional PaymentValidationErrors errorFields = {});
};

Note

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

10.1 `retry()` method

Note

If a PaymentResponse is found to be erroneous (e.g., a payment instrument has expired or shipping information is invalid), the retry() method affords the end user the ability to fix input errors and try to get the merchant to processed the payment again. The passed PaymentValidationErrors serve as hints as to where input errors have occurred in the PaymentResponse, which the end user needs to correct.

However, an end user may decide, upon inspection of the PaymentValidationErrors, to provide an entirely new set of values for the PaymentResponse. For example, the user might switch to a an entirely different payment instrument and/or provide an entirely different shipping address.

As such, merchants need to be prepared to completely revalidate a PaymentResponse once the [[retryPromise]] settles.

Lastly, as a PaymentResponse is inherently tied to a particular payment handler via a PaymentRequest, it is not possible for the end user to switch to a different payment handler during retry().

The retry(errorFields) method MUST act as follows:

Let response be this.
Let request be response.[[request]].
Let document be request's relevant global object's associated Document.
If document is not fully active, then return a promise rejected with an "AbortError" DOMException.
If response.[[complete]] is true, return a promise rejected with an "InvalidStateError" DOMException.
If response.[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
Set request.[[state]] to "interactive".
Let retryPromise be a new promise.
Set response.[[retryPromise]] to retryPromise.
If errorFields was passed:
1. If errorFields.paymentMethod member was passed, and if required by the specification that defines response.payment/a>, then convert errorFields's paymentMethod member to an IDL value of the type specified there. Otherwise, convert to object.
2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
3. If conversion results in a exception error:
  1. Reject retryPromise with error.
  2. Set user agent's payment request is showing boolean to false.
  3. Return.
4. By matching the members of errorFields to input fields in the user agent's UI, indicate to the end user that something is wrong with the data of the payment response. For example, a user agent might draw the user's attention to the erroneous errorFields in the browser's UI and display the value of each field in a manner that helps the user fix each error. Similarly, if the error member is passed, present the error in the user agent's UI. In the case where the value of a member is the empty string, the user agent MAY substitute a value with a suitable error message.
Otherwise, if errorFields was not passed, signal to the end user to attempt to retry the payment. Re-enable any UI element that affords the end user the ability to retry accepting the payment request.
If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
1. Close down the user interface.
2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
Finally, when retryPromise settles, set response.[[retryPromise]] to null.
Return retryPromise.
Note
The retryPromise will later be resolved by the user accepts the payment request algorithm, or rejected by either the user aborts the payment request algorithm or abort the update.

10.1.1 `PaymentValidationErrors` dictionary

WebIDLdictionary PaymentValidationErrors {
  DOMString error;
  object paymentMethod;
};

error member: A general description of an error with the payment from which the user can attempt to recover. For example, the user may recover by retrying the payment. A developer can optionally pass the error member on its own to give a general overview of validation issues, or it can be passed in combination with other members of the PaymentValidationErrors dictionary.
paymentMethod member: A payment method specific errors.

10.2 `methodName` attribute

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

10.3 `details` attribute

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

Note

10.4 `requestId` attribute

The corresponding payment request id that spawned this payment response.

10.5 `complete()` method

Note

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

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

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

The complete() method MUST act as follows:

Let response be this.
If response.[[complete]] is true, return a promise rejected with an "InvalidStateError" DOMException.
If response.[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
Let promise be a new promise.
Set response.[[complete]] to true.
Return promise and perform the remaining steps in parallel.
If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
1. Close down the user interface.
2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
Otherwise:
1. Close down any remaining user interface. The user agent MAY use the value result to influence the user experience.
2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
3. Resolve promise with undefined.

10.6 Internal Slots

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

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

12. Events

12.1 Summary

This section is non-normative.

Event name	Interface	Dispatched when…	Target
`paymentmethodchange`	`PaymentMethodChangeEvent`	The user chooses a different payment method within a payment handler.	`PaymentRequest`

MDN

PaymentMethodChangeEvent

Chrome	76+
Chrome Android	76+
Edge	No
Edge Mobile	?
Firefox	No
Firefox Android	No
Internet Explorer	No
Opera	63+
Opera Android	54+
Safari	12.1+
Safari iOS	12.2+
Samsung Internet	Yes
WebView Android	No

MDN

PaymentMethodChangeEvent/PaymentMethodChangeEvent

Chrome	76+
Chrome Android	76+
Edge	No
Edge Mobile	?
Firefox	No
Firefox Android	No
Internet Explorer	No
Opera	63+
Opera Android	54+
Safari	12.1+
Safari iOS	12.2+
Samsung Internet	Yes
WebView Android	No

12.2 `PaymentMethodChangeEvent` interface

WebIDL[SecureContext, Exposed=Window]
interface PaymentMethodChangeEvent : PaymentRequestUpdateEvent {
  constructor(DOMString type, optional PaymentMethodChangeEventInit eventInitDict = {});
  readonly attribute DOMString methodName;
  readonly attribute object? methodDetails;
};

12.2.1 `methodDetails` attribute

When getting, returns the value it was initialized with. See methodDetails member of PaymentMethodChangeEventInit for more information.

12.2.2 `methodName` attribute

When getting, returns the value it was initialized with. See methodName member of PaymentMethodChangeEventInit for more information.

12.2.3 `PaymentMethodChangeEventInit` dictionary

WebIDLdictionary PaymentMethodChangeEventInit : PaymentRequestUpdateEventInit {
  DOMString methodName = "";
  object? methodDetails = null;
};

methodName member: A string representing the payment method identifier.
methodDetails member: An object representing some data from the payment method, or null.

12.3 `PaymentRequestUpdateEvent` interface

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

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

12.3.1 `Constructor`

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

Let event be the result of calling the constructor of PaymentRequestUpdateEvent with type and eventInitDict.
Set event.[[waitForUpdate]] to false.
Return event.

12.3.2 `updateWith()` method

Note

The updateWith() with detailsPromise method MUST act as follows:

Let event be this.
If event's isTrusted attribute is false, then throw an "InvalidStateError" DOMException.
If event.[[waitForUpdate]] is true, then throw an "InvalidStateError" DOMException.
If event's target is an instance of PaymentResponse, let request be event's target's [[request]].
Otherwise, let request be the value of event's target.
Assert: request is an instance of PaymentRequest.
If request.[[state]] is not "interactive", then throw an "InvalidStateError" DOMException.
If request.[[updating]] is true, then throw an "InvalidStateError" DOMException.
Set event's stop propagation flag and stop immediate propagation flag.
Set event.[[waitForUpdate]] to true.
Let pmi be null.
If event has a methodName attribute, set pmi to the methodName attribute's value.
Run the update a PaymentRequest's details algorithm with detailsPromise, request, and pmi.

12.3.3 Internal Slots

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

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

12.3.4 `PaymentRequestUpdateEventInit` dictionary

WebIDLdictionary PaymentRequestUpdateEventInit : EventInit {};

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

13.1 Can make payment algorithm

The can make payment algorithm checks if the user agent supports making payment with the payment methods with which the PaymentRequest was constructed.

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 top-level browsing context's discretion, return a promise rejected with a "NotAllowedError" DOMException.
Note
This allows user agents to apply heuristics to detect and prevent abuse of the calling method for fingerprinting purposes, such as creating PaymentRequest objects with a variety of supported payment methods and triggering the can make payment algorithm 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 hasHandlerPromise be a new promise.
Return hasHandlerPromise, and perform the remaining steps in parallel.
For each paymentMethod tuple in request. [[serializedMethodData]]:
1. Let identifier be the first element in the paymentMethod tuple.
2. If the user agent has a payment handler that supports handling payment requests for identifier, resolve hasHandlerPromise with true and terminate this algorithm.
Resolve hasHandlerPromise with false.

13.2 Payment method changed algorithm

A payment handler MAY run the payment method changed algorithm when the user changes payment method with methodDetails, which is a dictionary or an object or null, and a methodName, which is a DOMString that represents the payment method identifier of the payment handler the user is interacting with.

Let request be the PaymentRequest object that the user is interacting with.
Queue a task on the user interaction task source to run the following steps:
1. Assert: request.[[updating]] is false. Only one update can take place at a time.
2. Assert: request.[[state]] is "interactive".
3. Fire an event named "paymentmethodchange" at request using PaymentMethodChangeEvent, with its methodName attribute initialized to methodName, and its methodDetails attribute initialized to methodDetails.

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

Assert: request.[[updating]] is false. Only one update can take place at a time.
Assert: request.[[state]] is "interactive".
Let event be the result of creating an event using the PaymentRequestUpdateEvent interface.
Initialize event's type attribute to name.
Dispatch event at request.
If event.[[waitForUpdate]] is true, disable any part of the user interface that could cause another update event to be fired.
Otherwise, set event.[[waitForUpdate]] to true.

13.4 User accepts the payment request algorithm

The user accepts the payment request algorithm runs when the user accepts the payment request and confirms that they want to pay. It MUST queue a task on the user interaction task source to perform the following steps:

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.
Let isRetry be true if request.[[response]] is not null, false otherwise.
Let response be request.[[response]] if isRetry is true, or a new PaymentResponse otherwise.
If isRetry if false, initialize the newly created response:
1. Set response.[[request]] to request.
2. Set response.[[retryPromise]] to null.
3. Set response.[[complete]] to false.
4. Set the requestId attribute value of response to the value of request.[[details]].id.
5. Set request.[[response]] to response.
Let handler be request.[[handler]].
Set the methodName attribute value of response to the payment method identifier of handler.
Set the details attribute value of response to an object resulting from running the handler's steps to respond to a payment request.
Set request.[[state]] to "closed".
If isRetry is true, resolve response.[[retryPromise]] with undefined. Otherwise, resolve request.[[acceptPromise]] with response.

13.5 User aborts the payment request algorithm

The user aborts the payment request algorithm runs when the user aborts the payment request through the currently interactive user interface. It MUST queue a task on the user interaction task source to perform the following steps:

Let request be the PaymentRequest object that the user is interacting with.
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.
Set request.[[state]] to "closed".
Set request's payment-relevant browsing context's payment request is showing boolean to false.
Let error be an "AbortError" DOMException.
Let response be request.[[response]].
If response is not null:
1. Set response.[[complete]] to true.
2. Assert: response.[[retryPromise]] is not null.
3. Reject response.[[retryPromise]] with error.
Otherwise, reject request.[[acceptPromise]] with error.
Abort the current user interaction and close down any remaining user interface.

13.6 Update a `PaymentRequest`'s details algorithm

The update a PaymentRequest's details algorithm takes a PaymentDetailsUpdate detailsPromise, a PaymentRequest request, and pmi that is either a DOMString or null (a payment method identifier). The steps are conditional on the detailsPromise settling. If detailsPromise never settles then the payment request is blocked. The user agent SHOULD provide the user with a means to abort a payment request. Implementations MAY choose to implement a timeout for pending updates if detailsPromise doesn't settle in a reasonable amount of time.

In the case where a timeout occurs, or the user manually aborts, or the payment handler decides to abort this particular payment, the user agent MUST run the user aborts the payment request algorithm.

Set request.[[updating]] to true.
In parallel, 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 user interface is updated with any new details.
Upon rejection of detailsPromise:
1. Abort the update with request and an "AbortError" DOMException.
Upon fulfillment of detailsPromise with value value:
1. Let details be the result of converting value to a PaymentDetailsUpdate dictionary. If this throw an exception, abort the update with request and with the thrown exception.
2. Let serializedModifierData be an empty list.
3. Validate and canonicalize the details:
  1. If the total member of details is present, then:
    1. Check and canonicalize total amount details.total.amount. If an exception is thrown, then abort the update with request and that exception.
  2. If the displayItems member of details is present, then for each item in details.displayItems:
    1. Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with request and that exception.
  3. If the modifiers member of details is present, then:
    1. Let modifiers be the sequence details.modifiers.
    2. Let serializedModifierData be an empty list.
    3. For each PaymentDetailsModifier modifier in modifiers:
      1. Run the steps to validate a payment method identifier with modifier.supportedMethods. If it returns false, then abort the update with request and a RangeError exception. Optionally, inform the developer that the payment method identifier is invalid.
      2. If the total member of modifier is present, then:
        
        Check and canonicalize total amount modifier.total.amount. If an exception is thrown, then abort the update with request and that exception.
      3. If the additionalDisplayItems member of modifier is present, then for each PaymentItem item in modifier.additionalDisplayItems:
        
        Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with request and that exception.
      4. If the data member of modifier is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing modifier.data into a string. If JSON-serializing throws an exception, then abort the update with request and that exception.
      5. Add serializedData to serializedModifierData.
      6. Remove the data member of modifier, if it is present.
4. If the paymentMethodErrors member is present and identifier is not null:
  1. If required by the specification that defines the pmi, then convert paymentMethodErrors to an IDL value.
  2. If conversion results in a exception error, abort the update with error.
  3. The payment handler SHOULD display an error for each relevant erroneous field of paymentMethodErrors.
5. Update the PaymentRequest using the new details:
  1. If the total member of details is present, then:
    1. Set request.[[details]].total to details.total.
  2. If the displayItems member of details is present, then:
    1. Set request.[[details]].displayItems to details.displayItems.
  3. If the modifiers member of details is present, then:
    1. Set request.[[details]].modifiers to details.modifiers.
    2. Set request.[[serializedModifierData]] to serializedModifierData.
Set request.[[updating]] to false.
Update the user interface based on any changed values in request. Re-enable user interface elements disabled prior to running this algorithm.

13.6.1 Abort the update

To abort the update with a PaymentRequest request and exception exception:

Optionally, show an error message to the user when letting them know an error has occurred.
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. Set request's payment-relevant browsing context's payment request is showing boolean to false.
2. Set request.[[state]] to "closed".
3. Let response be request.[[response]].
4. If response is not null, then:
  1. Set response.[[complete]] to true.
  2. Assert: response.[[retryPromise]] is not null.
  3. Reject response.[[retryPromise]] with exception.
5. Otherwise, reject request.[[acceptPromise]] with exception.
6. Set request.[[updating]] to false.
Abort the algorithm.

Note

Abort the update runs when there is a fatal error updating the payment request, such as the supplied detailsPromise rejecting, or its fulfillment value containing invalid data. This would potentially leave the payment request in an inconsistent state since the developer hasn't successfully handled the change event.

Consequently, the PaymentRequest moves to a "closed" state. The error is signaled to the developer through the rejection of the [[acceptPromise]], i.e., the promise returned by show().

Similarly, abort the update occurring during retry() causes the [[retryPromise]] to reject, and the corresponding PaymentResponse's [[complete]] internal slot will be set to true (i.e., it can no longer be used).

14. Privacy and Security Considerations

14.1 User protections with `show()` method

This section is non-normative.

To help ensure that users do not inadvertently share sensitive credentials with an origin, this API requires that PaymentRequest's show() method be invoked while the relevant Window has transient activation (e.g., via a click or press).

To avoid a confusing user experience, this specification limits the user agent to displaying one at a time via the show() method. In addition, the user agent can limit the rate at which a page can call show().

14.2 Secure contexts

This section is non-normative.

The API defined in this specification is only exposed in a secure context - see also the Secure Contexts specification for more details. In practice, this means that this API is only available over HTTPS. This is to limit the possibility of payment method data (e.g., credit card numbers) being sent in the clear.

14.3 Cross-origin payment requests

This section is non-normative.

It is common for merchants and other payees to delegate checkout and other e-commerce activities to payment service providers through an iframe. This API supports payee-authorized cross-origin iframes through [HTML]'s allow attribute.

Payment handlers have access to both the origin that hosts the iframe and the origin of the iframe content (where the PaymentRequest initiates).

14.4 Encryption of data fields

This section is non-normative.

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

14.5 How user agents match payment handlers

This section is non-normative.

As part of show(), the user agent typically displays a list of matching payment handlers that satisfy the payment methods accepted by the merchant and other conditions. Matching can take into account payment method information provided as input to the API, information provided by the payment method owner, the payment handlers registered by the user, user preferences, and other considerations.

For security reasons, a user agent can limit matching (in show() and canMakePayment()) to payment handlers from the same origin as a URL payment method identifier.

14.6 Data usage

Payment method owners establish the privacy policies for how user data collected for the payment method may be used. Payment Request API sets a clear expectation that data will be used for the purposes of completing a transaction, and user experiences associated with this API convey that intention. It is the responsibility of the payee to ensure that any data usage conforms to payment method policies. For any permitted usage beyond completion of the transaction, the payee should clearly communicate that usage to the user.

14.7 Exposing user information

The user agent MUST NOT share information about the user with a developer without user consent.

In particular, the PaymentMethodData's data and PaymentResponse's details members allow for the arbitrary exchange of data. In light of the wide range of data models used by existing payment methods, prescribing data specifics in this API would limit its usefulness. The details member carries data from the payment handler, whether Web-based (as defined by the Payment Handler API) or proprietary. The user agent MUST NOT support payment handlers unless they include adequate user consent mechanisms (such as awareness of parties to the transaction and mechanisms for demonstrating the intention to share data).

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

The PaymentMethodChangeEvent enables the payee to update the displayed total based on information specific to a selected payment method. For example, the billing address associated with a selected payment method might affect the tax computation (e.g., VAT), and it is desirable that the user interface accurately display the total before the payer completes the transaction. At the same time, it is desirable to share as little information as possible prior to completion of the payment. Therefore, when a payment method defines the steps for when a user changes payment method, it is important to minimize the data shared via the PaymentMethodChangeEvent's methodDetails attribute. Requirements and approaches for minimizing shared data are likely to vary by payment method.

Where sharing of privacy-sensitive information might not be obvious to users (e.g., when changing payment methods), it is RECOMMENDED that user agents inform the user of exactly what information is being shared with a merchant.

14.8 `canMakePayment()` protections

The canMakePayment() method provides feature detection for different payment methods. It may become a fingerprinting vector if in the future, a large number of payment methods are available. purposes. User agents are expected to protect the user from abuse of the method. For example, user agents can reduce user fingerprinting by:

Rate-limiting the frequency of calls with different parameters.

For rate-limiting the user agent might look at repeated calls from:

the same effective top-level domain plus one (eTLD+1).
the top-level browsing context. Alternatively, the user agent may block access to the API entirely for origins know to be bad actors.
the origin of an iframe or popup window.

These rate-limiting techniques intend to increase the cost associated with repeated calls, whether it is the cost of managing multiple eTLDs or the user experience friction of opening multiple windows (tabs or pop-ups).

Payment Request API

W3C Candidate Recommendation Draft 28 September 2021

Abstract

Status of This Document

Changes since last publication

1. Introduction

1.1 Goals and scope

2. Examples of usage

2.1 Declaring multiple ways of paying

2.2 Describing what is being paid for

2.3 Conditional modifications to payment request

2.4 Constructing a PaymentRequest

2.5 POSTing payment response back to a server

2.6 Using with cross-origin iframes

3. PaymentRequest interface

3.1 Constructor

3.2 id attribute

3.3 show() method

3.4 abort() method

3.5 canMakePayment() method

3.6 onpaymentmethodchange attribute

3.7 Internal Slots

4. PaymentMethodData dictionary

5. PaymentCurrencyAmount dictionary

5.1 Validity checkers

6. Payment details dictionaries

6.1 PaymentDetailsBase dictionary

6.2 PaymentDetailsInit dictionary

6.3 PaymentDetailsUpdate dictionary

7. PaymentDetailsModifier dictionary

8. PaymentItem dictionary

9. PaymentComplete enum

10. PaymentResponse interface

10.1 retry() method

10.1.1 PaymentValidationErrors dictionary

10.2 methodName attribute

10.3 details attribute

10.4 requestId attribute

10.5 complete() method

10.6 Internal Slots

11. Permissions Policy integration

12. Events

12.1 Summary

12.2 PaymentMethodChangeEvent interface

12.2.1 methodDetails attribute

12.2.2 methodName attribute

12.2.3 PaymentMethodChangeEventInit dictionary

12.3 PaymentRequestUpdateEvent interface

12.3.1 Constructor

12.3.2 updateWith() method

12.3.3 Internal Slots

12.3.4 PaymentRequestUpdateEventInit dictionary

13. Algorithms

13.1 Can make payment algorithm

13.2 Payment method changed algorithm

13.3 PaymentRequest updated algorithm

13.4 User accepts the payment request algorithm

13.5 User aborts the payment request algorithm

13.6 Update a PaymentRequest's details algorithm

13.6.1 Abort the update

14. Privacy and Security Considerations

14.1 User protections with show() method

14.2 Secure contexts

14.3 Cross-origin payment requests

14.4 Encryption of data fields

14.5 How user agents match payment handlers

14.6 Data usage

14.7 Exposing user information

14.8 canMakePayment() protections

15. Accessibility Considerations

16. Dependencies

17. Conformance

A. IDL Index

B. Acknowledgements

C. Changelog

D. References

D.1 Normative references

D.2 Informative references

2.4 Constructing a `PaymentRequest`

3. `PaymentRequest` interface

3.2 `id` attribute

3.3 `show()` method

3.4 `abort()` method

3.5 `canMakePayment()` method

3.6 `onpaymentmethodchange` attribute

4. `PaymentMethodData` dictionary

5. `PaymentCurrencyAmount` dictionary

6.1 `PaymentDetailsBase` dictionary

6.2 `PaymentDetailsInit` dictionary

6.3 `PaymentDetailsUpdate` dictionary

7. `PaymentDetailsModifier` dictionary

8. `PaymentItem` dictionary

9. `PaymentComplete` enum

10. `PaymentResponse` interface

10.1 `retry()` method

10.1.1 `PaymentValidationErrors` dictionary

10.2 `methodName` attribute

10.3 `details` attribute

10.4 `requestId` attribute

10.5 `complete()` method

12.2 `PaymentMethodChangeEvent` interface

12.2.1 `methodDetails` attribute

12.2.2 `methodName` attribute

12.2.3 `PaymentMethodChangeEventInit` dictionary

12.3 `PaymentRequestUpdateEvent` interface

12.3.1 `Constructor`

12.3.2 `updateWith()` method

12.3.4 `PaymentRequestUpdateEventInit` dictionary

13.6 Update a `PaymentRequest`'s details algorithm

14.1 User protections with `show()` method

14.8 `canMakePayment()` protections