Apple Pay on the Web Demo

Overview

The upper funnel merchandising element allows merchants of all sizes to highlight Apple Pay’s flexible payment options — such as available installment plans — using dynamic messaging throughout the consumer journey (e.g.: product detail pages, cart).

The feature consists of a widget and its accompanying modal. These provide additional information to the consumer about the variety of payment options with Apple Pay online, on iPhone or iPad¹.

This demo generates source code that you can copy into your own project.

Eligibility

The upper funnel merchandising element will only be displayed to eligible consumers when the following parameters are met:

They are on a supported OS version (iOS 18 or later / iPadOS 18 or later)
At least one financing partner is available for the given amount, currency, and country

Load the SDK

Add the following script tag to the <head> of your page. The apple-pay-merchandising component must be explicitly included in the components query parameter—it is not loaded by default.

<script crossorigin
      src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js?components=apple-pay-merchandising">
</script>

If you also need the Apple Pay button, include both components:

<script crossorigin
      src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js?components=apple-pay-button,apple-pay-merchandising">
</script>

Add the merchandising element

Add an <apple-pay-merchandising> element to your page and set the required amount, currency, and country attributes. When parameters are not met, the merchandising element will not be displayed to the consumer.

<apple-pay-merchandising
  amount="99.99"
  currency="USD"
  country="US"
  language="en-US"
  type="installments-logos"
  theme="light">
</apple-pay-merchandising>

Widget types

The merchandising element has a variety of widget messaging. Select the one that aligns best with your strategy and page layout:

installments-logos — Displays the logos of all eligible payment options for the transaction.
installments-text — Displays educational copy on how to find eligible installment options within the Apple Pay flow.
installments-how-to — A copy-only version that displays all eligible payment options.

Try it: Widget configuration

Use the type attribute to control the widget's visual layout.

Merchant Identifiers (Analytics)

Widget Styling

100%

450px

auto

80px

16px

11px

24px

28px

16px

Colors

No border Debug Mode

Generated Code

Configure parameters

The following attributes are supported on <apple-pay-merchandising>.

Attribute	Type	Required	Description
`amount`	String	Required	Transaction amount as a decimal String Example: `"99.99"`
`currency`	String (ISO 4217)	Required	Currency code Example: `"USD"`
`country`	String (ISO 3166‑1)	Required	Merchant country code Example: `"US"`
`language`	String (BCP 47)	Optional	Display language Example: `"en-US"`
`type`	String	Optional	Widget layout type (see Widget types) Example: `"installments-logos"`
`theme`	String	Optional	Color scheme: `auto` (default, follows system), `light`, or `dark` Example: `"light"`
`origin‑url`	String	Optional	Merchant's website origin URL for analytics segmentation Example: `"https://example.com"`
`apple‑pay‑mid`	String	Optional	Apple Pay Merchant Identifier for analytics segmentation Example: `"merchant.com.example.store"`
`merchant‑name`	String	Optional	Merchant's display name for analytics segmentation Example: `"Example Store"`
`debug`	Boolean	Optional	Enable debug mode for development (default: false). When true, bypasses platform restrictions and displays widget on any device, not just iOS/iPadOS. Example: `debug="true"`

Widget identifier

After the upper funnel merchandising element renders, it exposes a widgetIdentifier property. Include this value in your merchant session validation request so Apple can attribute conversions back to the element's impression.

// 1. Read the widget identifier from the widget
const widget = document.querySelector('apple-pay-merchandising');

// Read the widget identifier directly
const widgetIdentifier = widget.widgetIdentifier;

// 2. Send it to your server along with the validationURL
//    from the onvalidatemerchant callback
fetch('/your-server/validate-session', {
  method: 'POST',
  body: JSON.stringify({
    validationURL: event.validationURL,
    widgetIdentifier: widgetIdentifier
  })
});

// 3. On your server, include widgetIdentifier
//    in the payload when requesting a merchant session
//    from the Apple Pay validation endpoint

Theme and styling

The theme attribute accepts auto, light, or dark. When set to auto (the default), the upper funnel merchandising element follows the user’s system color scheme. Choose light or dark explicitly to match a fixed page background.

To switch themes dynamically—for example, in response to a toggle in your site’s UI—update the attribute with JavaScript:

const widget = document.querySelector('apple-pay-merchandising');
  widget.setAttribute('theme', 'dark');

Use standard CSS (width, max-width, margin) on the container element to control the placement of the upper funnel merchandising element within your page layout.

Additional resources

Ready to integrate the Upper Funnel Merchandising Element? Here are a few links you may find useful:

Questions or feedback

Check out our developer forums or reach out to us.

Disclosure

Demo page is accessible across any browser, including Safari, across all Apple devices; however, the upper funnel merchandising element will only be displayed on iPhone or iPad once integrated by the merchant.

¹ Paying over time on Apple Pay: Loans not offered by Apple. Subject to eligibility requirements and approval. Apple provides technical services for Paying Over Time on Apple Pay. Apple is not providing financial services, and all lending and payment services are provided to you by the relevant card issuer and lending provider. Not available in all markets, and may not be available for all types of purchases, such as subscriptions and recurring transactions. Available online and in-app on iPhone or iPad. May be available in-store on iPhone; in-store availability varies by location and is not guaranteed. Software requirements apply. Additional terms may apply. For more eligibility and feature details, see https://support.apple.com/120477.