Payment Request Button
The Payment Request Button Element gives you a single integration for Apple Pay, Google Pay, and browser-saved cards with Payment Request API such as Microsoft Pay on Edge.

The relevant button will be displayed automatically.
Customers see a Pay now button, an Apple Pay button or an Google Pay button, depending on what their device and browser combination supports. If no option is available, they don’t see the button. Supporting Apple Pay requires additional steps, but compatible devices automatically support browser-saved cards, Google Pay, and Microsoft Pay.
Apple Pay with the Payment Request Button requires macOS 10.12.1+ or iOS 10.1+.
Prerequisites
Before you start, you need to:
- Add a payment method to your browser. For example, you can save a card in Chrome, add a card to your Google Pay account or add a card to your Wallet for Safari.
- Serve your application over HTTPS. This is a requirement both in development and in production. One way to get up and running is to use a service like ngrok.
- Verify your domain with Apple Pay, both in development and production.
Verify your domain with Apple Pay
To use Apple Pay, you need to register with Apple all of your web domains that will show an Apple Pay button. This includes both top-level domains (for example, stripe.com) and subdomains (for example, shop.stripe.com). You need to do this for domains you use in both production and testing. When testing locally, use a tool like ngrok to get an HTTPS domain.
Important note: Apple’s documentation for Apple Pay on the Web describes their process of “merchant validation”, which Stripe handles for you behind the scenes. You don’t need to create an Apple Merchant ID, CSR, and so on, as described in their documentation, and should instead just follow these steps:
Download this domain association file and host it at
/.well-known/apple-developer-merchantid-domain-association
on your site.For example, if you’re registering
https://example.com
, make that file available athttps://example.com/.well-known/apple-developer-merchantid-domain-association
.Next, tell Stripe to register your domain with Apple. You can do this by either going to the Apple Pay tab in the Account Settings of your Dashboard, or by directly using the API with your live secret key as shown below.
We’ve redacted your live secret key here—head to your Dashboard and replace
sk_live_••••••••••••••••••••••••
below with your live secret key. All domains, whether in production or testing, must be registered with your live secret key.
- After registering your domains, you can make payments on your site using your live API keys.
Set up Stripe ElementsClient-side
Elements is available as part of Stripe.js. Include this in your page and create a container that will be used for the paymentRequestButton
Element:
<script src="https://js.stripe.com/v3/"></script> <div id="payment-request-button"> <!-- A Stripe Element will be inserted here. --> </div>
Your Stripe publishable API key is also required as it identifies your website to Stripe:
Create a paymentRequest instanceClient-side
Create an instance of stripe.paymentRequest
with all required options.
Use the requestPayerName
parameter to collect the payer’s billing address for Apple Pay. You can use the billing address to perform address verification and block fraudulent payments. All other payment methods automatically collect the billing address when one is available.
Create and mount the paymentRequestButtonClient-side
Create the paymentRequestButton
Element and check to make sure that your customer has an active payment method using canMakePayment()
. If they do, mount the Element to the container to display the Payment Request Button. If they don’t, you can’t mount the Element, and we encourage you to show a traditional checkout form instead.
If you accept Apple Pay with the Payment Request Button, you must offer Apple Pay as the primary payment option on your website per Apple guidelines. Internally, the Payment Request Button uses the Apple Pay canMakePaymentWithActiveCard
API.
Create a PaymentIntentServer-side
Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process.
Create a PaymentIntent
on your server with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious customers from being able to choose their own prices.
Included in the returned PaymentIntent is a client secret, which you’ll use to securely complete the payment process instead of passing the entire PaymentIntent object. Send the client secret back to the client to use in the next step.
Complete the paymentClient-side
Listen to the paymentmethod
event to receive a PaymentMethod object. Pass the PaymentMethod ID and the PaymentIntent’s client secret to stripe.confirmCardPayment to complete the payment.
The customer can dismiss the payment interface in some browsers even after they authorize the payment. This means that you might receive a cancel event on your PaymentRequest object after receiving a paymentmethod
event. If you’re using the cancel
event as a hook for canceling the customer’s order, make sure you also refund the payment that you just created.
Test your integration
To test your integration you must use HTTPS and a supported browser. If you are using the paymentRequestButton
Element within an iframe, the iframe must have the allow attribute set to equal “payment *”.
In addition, each payment method and browser has specific requirements:
Collect shipping information
To collect shipping information, begin by including requestShipping: true
when creating the payment request.
You may also provide an array of shippingOptions
at this point, if your shipping options don’t depend on the customer’s address.
Next, listen to the shippingaddresschange
event to detect when a customer selects a shipping address. Use the address to fetch valid shipping options from your server, update the total, or perform other business logic. The address data on the shippingaddresschange
event may be anonymized by the browser to not reveal sensitive information that is not necessary for shipping cost calculation.
The customer must supply valid shippingOptions
at this point to proceed in the flow.
Style the button
Use the following parameters to customize the Element:
Using your own button
If you wish to design your own button instead of using the paymentRequestButton
Element, you may show your custom button based on the result of paymentRequest.canMakePayment(). Then, use paymentRequest.show() to display the browser interface when your button is clicked.
When building your own button, follow Apple Pay’s Human Interface Guidelines and Google Pay’s Brand Guidelines.
Use the Payment Request Button with Stripe Connect
Connect platforms that either create direct charges or add the token to a Customer on the connected account must take some additional steps when using the Payment Request Button.
- On your frontend, before creating the
PaymentRequest
instance, set thestripeAccount
option on the Stripe instance:
- Register all domains on which the Payment Request Button will be shown with Apple Pay. You can use the Stripe API for this, using your platform’s secret key to authenticate the request, and setting the
Stripe-Account
header to your connected account’s Stripe ID, as described in Making API calls for connected accounts.
You must use your platform’s live secret key to register the domains; don’t add domains in test mode.
Use of Apple Pay on the web is subject to the Apple Pay on the web terms of service.