PaymentRequest.show()

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The PaymentRequest interface's show() method instructs the user agent to begin the process of showing and handling the user interface for the payment request to the user.

For security reasons, the PaymentRequest.show() method can't just be initiated at any time. It may only be called while handling events that represent user interactions, such as click, keyup, or the like.

Only one payment request can be in the process of being handled at once, across all documents. Once one PaymentRequest's show() method has been called, any other call to show() will by rejected with an AbortError until the returned promise has been concluded, either by being fulfilled with a PaymentResponse indicating the results of the payment request, or by being rejected with an error.

If your architecture doesn't necessarily have all of the data ready to go at the moment it instantiates the payment interface by calling show(), specify the detailsPromise parameter, providing a Promise that is fulfilled once the data is ready. If this is provided, show() will not allow the user to interact with the payment interface until the promise is fulfilled, so that data can be updated prior to the user engaging with the payment process.

Syntax

paymentRequest.show(detailsPromise)
  .then(paymentResponse => { ... })
  .catch(error => { ... })

Parameters

detailsPromise Optional
An optional Promise that you can provide if your architecture requires that the payment request's details need to be updated between instantiating the payment interface and the user beginning to interact with it. The promise should resolve with a PaymentDetailsUpdate object containing the updated information.

Returns

A Promise that eventually resolves with a PaymentResponse. The promise is resolved when the user accepts the payment request (i.e., when they hit "Pay" in the browser's payment sheet).

Exceptions

AbortError
The returned promise rejects with an AbortError if the user agent's "payment request is showing" Boolean is true; i.e. another payment has already been shown for this request.
InvalidStateError
The promise rejects with an InvalidStateError if the same payment has already been shown for this request (its state is interactive because it is being shown already).
NotSupportedError
The promise rejects with a NotSupportedError if the user agent does not support the payment methods specified when the PaymentRequest constructor was called.
SecurityError
The promise rejects with a SecurityError if the user agent disallows the method call for some reason (e.g. too many show() calls have been made in a short amount of time, or it doesn't allow show() calls that aren't initiated by a user action).

Examples

In the following example, a PaymentRequest object is instantiated before the show() method is called. This method triggers the user agent's built-in process for retrieving payment information from the user. The show() method returns a Promise that resolves to a PaymentResponse object when the user interaction is complete. The developer then uses the information in the PaymentResponse object to format and send payment data to the server. You should send the payment information to the server asynchronously so that the final call to paymentResponse.complete() can indicate the success or failure of the payment.

button.onclick = async function handlePurchase() {
  // Initialization of PaymentRequest arguments are excerpted for the sake of
  // brevity. 
  const payment = new PaymentRequest(methods, details, options);
  try {
    const response = await payment.show();
    // Process response here, including sending payment instrument
    // (e.g., credit card) information to the server.
    // paymentResponse.methodName contains the selected payment method
    // paymentResponse.details contains a payment method specific response
    await response.complete("success");
  } catch (err) {
    console.error("Uh oh, something bad happened", err.message);
  }
}

The following example shows how to update the payment sheet as it's being presented to the end-user.

async function requestPayment() {
  // We start with AU$0 as the total.
  const initialDetails = {
    total: {
      label: "Total",
      amount: { value: "0", currency: "AUD" },
    },
  };
  const request = new PaymentRequest(methods, initialDetails, options);
  // Check if the the user supports the `methods`
  if (!await request.canMakePayment()) {
    return; // no, so use a web form instead.
  }
  // Let's update the total as the sheet is shown
  const updatedDetails = {
    total: {
      label: "Total",
      amount: { value: "20", currency: "AUD" },
    },
  };
  const response = await request.show(updatedDetails);
  // Check response, etc...
}

document.getElementById("buyButton").onclick = requestPayment;

Specifications

Specification Status Comment
Payment Request API
The definition of 'show(optional detailsPromise)' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic support
Experimental
Chrome Full support 61
Disabled
Full support 61
Disabled
Disabled From version 61: this feature is behind the #web-payments preference (needs to be set to Enabled). To change preferences in Chrome, visit chrome://flags.
Edge Full support 15Firefox Full support 55
Disabled
Full support 55
Disabled
Disabled From version 55: this feature is behind the dom.payments.request.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android Full support 53
Disabled
Full support 53
Disabled
Disabled From version 53: this feature is behind the #web-payments preference (needs to be set to Enabled). To change preferences in Chrome, visit chrome://flags.
Edge Mobile Full support YesFirefox Android Full support 55
Disabled
Full support 55
Disabled
Disabled From version 55: this feature is behind the dom.payments.request.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS ? Samsung Internet Android Full support 6.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
User must explicitly enable this feature.
User must explicitly enable this feature.

See also

Document Tags and Contributors

Last updated by: Sheppy,