@economist/web-apple-pay

Framework-agnostic Apple Pay UI components implemented as Web Components.

This package provides:

• teg-apple-pay-button
• teg-apple-pay-modal

It is intentionally UI-focused. Consumer applications own backend payment orchestration, merchant validation, and secret handling.

Requirements

• Node.js 20.x or later
• npm 10.x or later

Installation

npm install --save @economist/web-apple-pay

Quick start

1) Configure runtime values

Call configureApplePay(...) once during app startup, before rendering Apple Pay UI:

import { configureApplePay, defineApplePayElements } from '@economist/web-apple-pay';

configureApplePay({
  merchantId: 'merchant.com.economist.your-app',
  debugBypassEnabled: false,
  // required: wallet API base URL for session and checkout calls
  walletApiBaseUrl: 'https://bff-test.economist.com',
});

defineApplePayElements();

2) Create and mount a button

import type { Offer, ApplePayButton } from '@economist/web-apple-pay';

const button = document.createElement('teg-apple-pay-button') as ApplePayButton;
button.offer = offer as Offer;
button.country = 'US';
button.dataset.loggedIn = 'true';

container.appendChild(button);

When clicked, the button creates and opens teg-apple-pay-modal automatically.

Runtime configuration

configureApplePay(config)

Sets package-level runtime configuration used by Apple Pay availability checks. Call this once during app startup.

config shape:

• merchantId (string, required): Apple Pay merchant identifier used for active-card checks.
• debugBypassEnabled (boolean, optional): allows ?BYPASS_APPLE_PAY_CHECKS=1 query param to bypass capability checks in non-production-style debugging flows.
• walletApiBaseUrl (string, required): base URL for wallet API requests.

If merchantId is not configured, Apple Pay availability checks return false and the button hides itself.

Component behavior

ApplePayButton

• Requires offer and country before click flow is meaningful.
• Checks Apple Pay availability on connect; if unavailable, it hides.
• Skips rendering for excluded variants (bundle, insider_print).
• Forwards data-logged-in from button to modal (modal.dataset.loggedIn).

Awaiting render completion — whenReady()

Use whenReady() to await the component's render lifecycle after appending it to the DOM. This is the supported, stable way to know whether Apple Pay is available without touching lifecycle internals.

container.appendChild(btn);   // spec-compliant — browser fires connectedCallback naturally
await btn.whenReady();        // resolves when rendering is complete
if (btn.style.display !== 'none') {
  // Apple Pay rendered successfully
} else {
  btn.remove(); // unavailable or suppressed
}

Important: calling whenReady() before appendChild resolves immediately to undefined — it does not wait for a future connection. Always call it after appending the element.

ApplePayModal

• Opened by ApplePayButton click.
• Emits apple-pay-confirmed when CTA is accepted.
• Escape closes the modal and prevents propagation to other global handlers.

Events

apple-pay-confirmed

Dispatched from ApplePayModal as a CustomEvent with:

• detail.skuId (string)
• detail.country (string)

Consumers should listen for this event and continue payment orchestration.

Public API

• defineApplePayElements(): registers both custom elements.
• configureApplePay(config): sets required runtime config (merchant ID and wallet API base URL, with optional debug bypass).
• ApplePayButton: button component class.
  • whenReady(): Promise<void> — resolves when the current render lifecycle completes (available or hidden). Resolves immediately if called before the element is connected.
• ApplePayModal: modal component class.
• ensureApplePayLogoSymbol(): logo symbol injection helper.
• Offer: offer contract type used by component props.

Troubleshooting

Button does not appear

Check:

• configureApplePay(...) was called before rendering (with a valid merchantId and walletApiBaseUrl)
• device/browser supports Apple Pay checks (Safari/Apple device logic)
• query string/feature flag gating for your page is satisfied
• offer variant is not excluded (bundle, insider_print)

Logged-in checkbox copy looks wrong

Set button.dataset.loggedIn = 'true' before appending the button. The button forwards this flag to the modal automatically.

Security and responsibilities

Merchant setup must be handled by the consuming application:

• inject merchant config at runtime
• perform merchant validation on trusted backend services
• keep certificates/secrets outside this package

Local development

From shared-packages:

cd packages/web-apple-pay
npm run build
yalc publish --sig

Then in a consuming app:

yalc add @economist/web-apple-pay

Storybook

Run Storybook locally:

npm run storybook --workspace @economist/web-apple-pay

Build static Storybook output:

npm run build-storybook --workspace @economist/web-apple-pay

Story coverage matrix:

• ApplePayButton docs page shows the stable default example.
• ApplePayButton behavior and state variants are available as individual canvas stories in Storybook.
• ApplePayModal docs page shows the stable default example.
• ApplePayModal behavior and state variants are available as individual canvas stories in Storybook.