mq-apple-pay-checkout

<mq-apple-pay-checkout> handles Apple Pay on top-level pages (not inside WKWebView or iframes). The host page must load the pinned Apple Pay JS SDK before mounting the element. The component renders Apple's official <apple-pay-button>, validates the merchant with the backend, authorizes the payment token, and emits the same outcome events as <mq-checkout>.

On Chrome, Edge, and Firefox (desktop), Apple Pay uses a QR modal — the user scans with an iPhone running iOS 18+ to complete payment. On Safari, the native Apple Pay sheet is used.

Use it from the checkout shell at /apple-pay, or mount it directly in your own top-level page on a domain verified with Apple.

How it works

1. The host loads the Apple Pay JS SDK (script-src + CSP must allow applepay.cdn-apple.com).
2. You pass merchant-id, session-id (backend order_id), and payment request metadata (amount, currency, country, label).
3. <mq-apple-pay-checkout> authenticates (api-key + token).
4. After applePayCapabilities(merchant-id) (or canMakePayments fallback), it renders the Apple Pay button and optional QR helper copy.
5. On click (user gesture): ApplePaySession → validate-merchant → authorize → outcome events.

POST /payments/v1/apple-pay/validate-merchant returns Apple's merchant session JSON at the HTTP body root (not MediQuo's { data: … } envelope). The component passes that object to completeMerchantValidation. POST /payments/v1/apple-pay/authorize uses the usual { data: { status, consultation_id } } shape; only status: "paid" is treated as success.

Dependencies

Does not require <mq-theme-provider> — the button uses Apple's SDK styling.

Does not require <mq-query-client-provider> or <mq-socket-provider>.

Does require the host to load the Apple Pay JS SDK. The component never injects third-party scripts.

Installation

npm install @mediquo/web-components

import "@mediquo/web-components/mq-apple-pay-checkout";

Usage

<script
  src="https://applepay.cdn-apple.com/jsapi/v1.3.8/apple-pay-sdk.js"
  integrity="sha384-u/9mOkmShCO0v+dqCAZFhiutJuORfzvuyM5i+676iy7mLSWS6rlllHrIt15f/mqH"
  crossorigin="anonymous"
></script>

<mq-apple-pay-checkout
  env="production"
  api-key="<your-api-key>"
  token="<your-token>"
  locale="es_ES"
  merchant-id="merchant.com.example"
  session-id="<order-id>"
  amount="29.99"
  currency="EUR"
  country="ES"
  label="Consulta"
></mq-apple-pay-checkout>

<script type="module">
  const checkout = document.querySelector("mq-apple-pay-checkout");

  checkout.addEventListener("payment-success", (e) => {
    console.log("paid", e.detail.sessionId, e.detail.reference);
  });
</script>

Attributes

Events

Platform requirements

• Top-level only — not inside WKWebView or iframes.
• The page must be served from a domain registered with Apple Pay (checkout.mediquo.com).
• Host must load the Apple Pay JS SDK and configure CSP (script-src, frame-src, connect-src for Apple hosts).
• Chrome / Edge / Firefox (desktop): QR flow requires an iPhone with iOS 18+.
• Safari: native Apple Pay sheet (SDK may also be loaded; session API is unchanged).

Native apps (recommended integration)

Mobile apps that schedule on-device and only need MediQuo for payment should not use <mq-schedule>. Open the hosted checkout directly:

The method selector belongs in the native UI. Apple Pay Web will fail inside a normal in-app WebView; only a Safari-class browser or desktop QR flow on the verified domain works.

Outcomes are relayed the same way as the card checkout (payment-success / payment-denied / payment-error → native bridge). If you open Safari externally, complete the return path with a deep / universal link.