Try it out with a supported browser. Don’t worry, your card won’t be charged.

For a complete example integrating the paymentRequestButton Element with a backend to process payments, check out this sample e-commerce store and browse its source code on GitHub.

The Payment Request API

The Payment Request API is a cross-browser standard that facilitates the exchange of your customer’s stored payment, address and contact information between the browser and your site.

For example, if your customer previously stored their card details in Chrome, the Payment Request API enables you to request that information from the browser, instead of having your customer fill out a full checkout form.

Stripe’s implementation of the Payment Request API is fully compatible with Stripe’s products and features (e.g., subscriptions), allowing you to use it in place of a traditional payment form whenever possible. Use it to accept payments for physical or digital goods, donations, subscriptions, and more (note that the Payment Request API is for use in browsers, not mobile applications).

Supported browsers and payment methods

The Payment Request API is supported by the following browsers as of April 2018:

• Chrome Desktop
• Chrome Android
• Microsoft Edge for Windows

The following payment methods are supported:

• Cards
• Google Pay, including Android Pay
• Microsoft Pay

Note that in all cases, your customer must have an active payment method available. If they do not, we encourage you to show a traditional checkout form instead.

Customer experience

After your customer initiates the Payment Request API interaction by clicking on the Payment Request Button, the browser will take over and request that they select what information to share with your site.

Chrome Desktop

Chrome Mobile

Microsoft Edge for Windows

Integrate the button

Collecting your customers’ payment information using the Payment Request Button Element requires four steps:

1. Set up Stripe Elements
2. Create the PaymentRequest instance
3. Create and mount the paymentRequestButton Element
4. Complete the payment using the emitted Token or PaymentMethod

Prerequisites

Before you start, you need to:

• Add a payment method to your browser. For example, you can save a card in Chrome, 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 to set up an SSH tunnel.
• Register your domain with Apple Pay, both in development and production.

Step 1: Set up Stripe Elements

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:

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

Step 2: Create the PaymentRequest instance

Create an instance of stripe.paymentRequest with all required options.

var paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});

const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});

Step 3: Create and mount the paymentRequestButton Element

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 do not, you cannot mount the Element, and we encourage you to show a traditional checkout form instead.

var elements = stripe.elements();
var prButton = elements.create('paymentRequestButton', {
  paymentRequest: paymentRequest,
});

// Check the availability of the Payment Request API first.
paymentRequest.canMakePayment().then(function(result) {
  if (result) {
    prButton.mount('#payment-request-button');
  } else {
    document.getElementById('payment-request-button').style.display = 'none';
  }
});

const elements = stripe.elements();
const prButton = elements.create('paymentRequestButton', {
  paymentRequest,
});

(async () => {
  // Check the availability of the Payment Request API first.
  const result = await paymentRequest.canMakePayment();
  if (result) {
    prButton.mount('#payment-request-button');
  } else {
    document.getElementById('payment-request-button').style.display = 'none';
  }
})();

Step 4: Complete the payment using the emitted Token or PaymentMethod

paymentRequest.on('token', function(ev) {
  // Send the token to your server to charge it!
  fetch('/charges', {
    method: 'POST',
    body: JSON.stringify({token: ev.token.id}),
    headers: {'content-type': 'application/json'},
  })
  .then(function(response) {
    if (response.ok) {
      // Report to the browser that the payment was successful, prompting
      // it to close the browser payment interface.
      ev.complete('success');
    } else {
      // Report to the browser that the payment failed, prompting it to
      // re-show the payment interface, or show an error message and close
      // the payment interface.
      ev.complete('fail');
    }
  });
});

paymentRequest.on('token', async (ev) => {
  // Send the token to your server to charge it!
  const response = await fetch('/charges', {
    method: 'POST',
    body: JSON.stringify({token: ev.token.id}),
    headers: {'content-type': 'application/json'},
  });

  if (response.ok) {
    // Report to the browser that the payment was successful, prompting
    // it to close the browser payment interface.
    ev.complete('success');
  } else {
    // Report to the browser that the payment failed, prompting it to
    // re-show the payment interface, or show an error message and close
    // the payment interface.
    ev.complete('fail');
  }
});

paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmPaymentIntent(clientSecret, {
    payment_method: ev.paymentMethod.id,
  }).then(function(confirmResult) {
    if (confirmResult.error) {
      // Report to the browser that the payment failed, prompting it to
      // re-show the payment interface, or show an error message and close
      // the payment interface.
      ev.complete('fail');
    } else {
      // Report to the browser that the confirmation was successful, prompting
      // it to close the browser payment method collection interface.
      ev.complete('success');
      // Let Stripe.js handle the rest of the payment flow.
      stripe.handleCardPayment(clientSecret).then(function(result) {
        if (result.error) {
          // The payment failed -- ask your customer for a new payment method.
        } else {
          // The payment has succeeded.
        }
      });
    }
  });
});

paymentRequest.on('paymentmethod', async (ev) => {
  const {
    error: confirmError,
    paymentIntent,
  } = await stripe.confirmPaymentIntent(clientSecret, {
    payment_method: ev.paymentMethod.id,
  });

  if (confirmError) {
    // Report to the browser that the payment failed, prompting it to
    // re-show the payment interface, or show an error message and close
    // the payment interface.
    ev.complete('fail');
  } else {
    // Report to the browser that the confirmation was successful, prompting
    // it to close the browser payment method collection interface.
    ev.complete('success');
    // Let Stripe.js handle the rest of the payment flow.
    const {error} = await stripe.handleCardPayment(clientSecret);
    if (error) {
      // The payment failed -- ask your customer for a new payment method.
    } else {
      // The payment has succeeded.
    }
  }
});

Collecting 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 do not depend on the customer’s address.

var paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },

  requestShipping: true,
  // `shippingOptions` is optional at this point:
  shippingOptions: [
    // The first shipping option in this list appears as the default
    // option in the browser payment interface.
    {
      id: 'free-shipping',
      label: 'Free shipping',
      detail: 'Arrives in 5 to 7 days',
      amount: 0,
    },
  ],
});

const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },

  requestShipping: true,
  // `shippingOptions` is optional at this point:
  shippingOptions: [
    // The first shipping option in this list appears as the default
    // option in the browser payment interface.
    {
      id: 'free-shipping',
      label: 'Free shipping',
      detail: 'Arrives in 5 to 7 days',
      amount: 0,
    },
  ],
});

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 anynomized by the browser to not reveal sensitive information that is not necessary for shipping cost calculation.

Note that valid shippingOptions must be supplied at this point for the customer to proceed in the flow.

paymentRequest.on('shippingaddresschange', function(ev) {
  if (ev.shippingAddress.country !== 'US') {
    ev.updateWith({status: 'invalid_shipping_address'});
  } else {
    // Perform server-side request to fetch shipping options
    fetch('/calculateShipping', {
      data: JSON.stringify({
        shippingAddress: ev.shippingAddress
      })
    }).then(function(response) {
      return response.json();
    }).then(function(result) {
      ev.updateWith({
        status: 'success',
        shippingOptions: result.supportedShippingOptions,
      });
    });
  }
});

paymentRequest.on('shippingaddresschange', async (ev) => {
  if (ev.shippingAddress.country !== 'US') {
    ev.updateWith({status: 'invalid_shipping_address'});
  } else {
    // Perform server-side request to fetch shipping options
    const response = await fetch('/calculateShipping', {
      data: JSON.stringify({
        shippingAddress: ev.shippingAddress
      })
    });
    const result = await response.json();

    ev.updateWith({
      status: 'success',
      shippingOptions: result.supportedShippingOptions,
    });
  }
});

Styling the Payment Request Button Element

Use the following parameters to customize the Element:

elements.create('paymentRequestButton', {
  paymentRequest: paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'default' | 'donate' | 'buy', // default: 'default'
      theme: 'dark' | 'light' | 'light-outline', // default: 'dark'
      height: '64px', // default: '40px', the width is always '100%'
    },
  },
});

elements.create('paymentRequestButton', {
  paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'default' | 'donate' | 'buy', // default: 'default'
      theme: 'dark' | 'light' | 'light-outline', // default: 'dark'
      height: '64px', // default: '40px', the width is always '100%'
    },
  },
});

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.

Verifying 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 (e.g., stripe.com) and subdomains (e.g., 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 do not need to create an Apple Merchant ID, CSR, etc., as described in their documentation, and should instead just follow these steps:

1. 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 at https://example.com/.well-known/apple-developer-merchantid-domain-association.

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

   Note that 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.

   curl https://api.stripe.com/v1/apple_pay/domains \
    -u "sk_live_••••••••••••••••••••••••": \
    -d domain_name="example.com"

   Stripe.api_key = "sk_live_••••••••••••••••••••••••"
   Stripe::ApplePayDomain.create({
     domain_name: 'example.com',
   })

   stripe.api_key = "sk_live_••••••••••••••••••••••••"
   stripe.ApplePayDomain.create(
     domain_name="example.com"
   )

   \Stripe\Stripe::setApiKey("sk_live_••••••••••••••••••••••••");
   \Stripe\ApplePayDomain::create([
     'domain_name' => 'example.com'
   ]);

   var stripe = require("stripe")("sk_live_••••••••••••••••••••••••");
   stripe.applePayDomains.create({
     domain_name: 'example.com'
   });

   Stripe.apiKey = "sk_live_••••••••••••••••••••••••";
   Map<String, Object> domainParams = new HashMap<String, Object>();
   domainParams.put("domain_name", "example.com");
   ApplePayDomain.create(domainParams);

3. After registering your domains, you can make payments on your site using your live API keys.

Testing 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 allowpaymentrequest attribute set.

In addition, each payment method and browser has specific requirements:

Safari

• Safari on Mac running macOS Sierra or later.
• An iPhone (not an iPad; Safari doesn't support them yet) with a card in its Wallet paired to your Mac with Handoff, or a Mac with TouchID. Instructions can be found on Apple's Support website.
• Make sure you've verified your domain with Apple Pay.
• When using an iframe, its origin must match the top-level origin. Two pages have the same origin if the protocol, host (full domain name), and port (if one is specified) are the same for both pages.

Mobile Safari

• Mobile Safari on iOS 10.1 or later.
• A card in your Wallet, by going to Settings → Wallet & Apple Pay.
• Make sure you've verified your domain with Apple Pay.
• When using an iframe, its origin must match the top-level origin. Two pages have the same origin if the protocol, host (full domain name), and port (if one is specified) are the same for both pages.

Chrome

• Chrome 61 or newer.
• A saved payment card.

Chrome Mobile for Android

• Chrome 61 or newer.
• An activated Google Pay card or a saved card.

Note that when using Google Pay, including Android Pay, with a test mode key, you might see an "Unrecognized app" warning. This is expected, and does not show up in live mode.

Microsoft Edge for Windows

• Microsoft Edge 16.16299 or newer.
• A saved payment card.

Using the Payment Request Button with Stripe Connect (optional)

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.

1. On your frontend, before creating the PaymentRequest instance, set the stripeAccount option on the Stripe instance:

   var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
     stripeAccount: 'CONNECTED_STRIPE_ACCOUNT_ID'
   });

   const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
     stripeAccount: 'CONNECTED_STRIPE_ACCOUNT_ID'
   });

2. 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 Authentication with Connect.

   curl https://api.stripe.com/v1/apple_pay/domains \
   -u {PLATFORM_SECRET_KEY}: \
   -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
   -d domain_name="example.com"

Next steps

Congrats! You’re now using the Payment Request Button to collect your customer’s information with Stripe. Once you’ve sent your token to your server, you’ll be able to use the token to perform a charge or to save to a customer.

• Start creating charges
• Learn about Apple Pay
• Learn about Google Pay
• Learn about Microsoft Pay
• Build a standard credit card form with Elements