Payment Request Button

The Payment Request Button Element gives you a single integration for Apple Pay, Google Pay, and Link—Stripe’s one-click checkout experience.

The relevant button will be displayed automatically.

The Payment Request Button dynamically displays wallet options to optimize the checkout experience for your customers. Customers see Apple Pay or Google Pay if they’ve enabled them on their device, and depending on what browser they are using. If a customer doesn’t have Apple Pay or Google Pay enabled on their device, they see Link. Additionally, customers using Chrome with active, authenticated Link sessions see Link.

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

<script src="https://js.stripe.com/v3/"></script>
<div id="payment-request-button">
  <!-- A Stripe Element will be inserted here. -->
</div>

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx', {
  apiVersion: "2022-11-15",
});

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

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';
  }
})();

Create a PaymentIntent

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

curl

Ruby

Python

PHP

Java

Node

Go

.NET

Command Line

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="usd"

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.

paymentRequest.on('paymentmethod', async (ev) => {
  // Confirm the PaymentIntent without handling potential next actions (yet).
  const {paymentIntent, error: confirmError} = await stripe.confirmCardPayment(
    clientSecret,
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  );

  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');
    // Check if the PaymentIntent requires any actions and if so let Stripe.js
    // handle the flow. If using an API version older than "2019-02-11"
    // instead check for: `paymentIntent.status === "requires_source_action"`.
    if (paymentIntent.status === "requires_action") {
      // Let Stripe.js handle the rest of the payment flow.
      const {error} = await stripe.confirmCardPayment(clientSecret);
      if (error) {
        // The payment failed -- ask your customer for a new payment method.
      } else {
        // The payment has succeeded.
      }
    } else {
      // The payment has succeeded.
    }
  }
});

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.

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

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

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,
    });
  }
});

Display line items

Use displayItems to display PaymentItem objects and surface price breakdown in the browser’s payment interface.

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

  displayItems: [
    {
      label: 'Sample item',
      amount: 1000,
    },
    {
      label: 'Shipping cost',
      amount: 1000,
    }
  ],
});

Style the button

Use the following parameters to customize the Element:

elements.create('paymentRequestButton', {
  paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'default',
      // One of 'default', 'book', 'buy', or 'donate'
      // Defaults to 'default'

      theme: 'dark',
      // One of 'dark', 'light', or 'light-outline'
      // Defaults to 'dark'

      height: '64px',
      // Defaults to '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 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.

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

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx', {
  apiVersion: "2022-11-15",
  stripeAccount: 'CONNECTED_STRIPE_ACCOUNT_ID',
});

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

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

Link for Payment Request Button

Link is Stripe’s one-click checkout experience. Link lets your customers securely save their payment information and re-use it on your site and across hundreds of thousands of businesses for faster checkout. When new customers come to your site, they can use Link via the Payment Request Button to pay with their saved payment details. With Link, customers skip the hassle of manually entering their payment information, resulting in:

• Faster checkout
• Higher likelihood of purchase completion
• Increased customer purchase frequency

Link is fully compatible with the other features you receive from card payments (subscriptions, etc). There are no additional fees. The same pricing applies to Link for Payment Request Button as for other card payments.

Over time, we’ll increase the number of funding sources customers can pay with through their Link account to match local payment method preferences.