Apple Pay Knowledge Patch

Apple Pay Knowledge Patch

Use this skill for Apple Pay work involving:

• Apple Pay JS or Payment Request platform availability.
• SDK delivery, sandbox behavior, or a pinned SDK asset.
• Apple Pay button behavior.
• Merchandising and order-tracking components on the web.
• Recurring, automatic-reload, or deferred payment requests.
• Multimerchant token contexts.
• Merchant-validation sheet updates.
• Merchant category codes on payment requests.

Reference index

Apply the guidance

1. Identify the integration surface.
   • For browser and operating-system eligibility, use Web platform and SDK.
   • For payment-request modeling, use Payment requests.
   • For installment information or order tracking, use Merchandising and order tracking.
2. Preserve the regional distinction in web platform checks.
   • Outside China and China have different minimum iOS versions.
   • macOS availability also differs by region.
3. Keep Apple Pay JS and Payment Request requirements separate.
   • Their minimum iOS versions differ.
   • Their minimum macOS requirements differ outside China.
4. Treat sandbox capability results according to the sandbox-specific rule.
   • paymentCredentialStatusUnknown is not proof that Apple Pay is unavailable.
5. Select only the payment-request primitive that matches the stated payment schedule or update.

Quick reference: web platform boundaries

Outside China

China

On iOS in China, both Safari and SFSafariViewController support Apple Pay.

Quick reference: SDK and button

SDK delivery

A site can load either:

• The latest autoupdating Apple Pay JS SDK.
• A chosen Apple Pay JS SDK version.

For the exact versioned 1.3.8 CDN URL and Subresource Integrity hash, use Pinned 1.3.8 asset.

Button behavior

ApplePayButton can:

• Start a payment.
• Prompt the customer to set up a card.

Sandbox behavior

Apple Pay JS 1.3.5 added sandbox environment configuration. In sandbox mode:

• The UI displays a “Sandbox Mode” banner.
• The console reports the environment.
• applePayCapabilities returns paymentCredentialStatusUnknown in supported browsers.

Do not treat that status as proof that Apple Pay is unavailable.

Quick reference: payment requests

Specialized schedules

Multimerchant tokens

PKPaymentTokenContext defines the context for one payment token in a multimerchant payment request.

Merchant validation

PKPaymentRequestMerchantSessionUpdate updates a payment request with merchant validation.

Merchant category code

PKPaymentRequest.merchantCategoryCode optionally attaches an MCC that categorizes the merchant's goods or services for the payment transaction.

Quick reference: web presentation

Installment merchandising

The Apple Pay Merchandising web component displays:

• Installment-payment options.
• Related merchandising information on a seller's site.

Order tracking

A website can configure and style a Track with Apple Wallet button to match the rest of the site.

Integration checks

Browser eligibility

• Determine whether the integration is inside or outside China.
• Determine whether the integration uses Apple Pay JS or Payment Request.
• Apply the matching iOS minimum.
• Outside China, apply the matching macOS minimum and the Safari minimum stated for Payment Request.
• In China, do not treat either web API as available on macOS.
• On iOS in China, account for support in Safari and SFSafariViewController.

SDK selection

• Decide between the latest autoupdating SDK and a chosen version.
• When pinning version 1.3.8 with SRI, copy the published URL, integrity hash, and crossorigin attribute from the reference.
• When using sandbox environment configuration, expect the banner and console report.
• Do not convert paymentCredentialStatusUnknown into an unavailable result.
• Choose whether ApplePayButton starts payment or prompts card setup.

Payment-request modeling

• Use PKRecurringPaymentRequest for a subscription.
• Use PKAutomaticReloadPaymentRequest for a reload such as a prepaid-account top-up.
• Use PKDeferredPaymentRequest for a charge such as a hotel booking or preorder.
• Use one PKPaymentTokenContext to define the context for one payment token in a multimerchant payment request.
• Use PKPaymentRequestMerchantSessionUpdate to update a payment request with merchant validation.
• Attach an MCC through PKPaymentRequest.merchantCategoryCode when the payment request should categorize the merchant's goods or services.

Customer-facing web elements

• Use the Apple Pay Merchandising web component to display installment-payment options and related merchandising information.
• Configure and style the Track with Apple Wallet button to match the site.

Fidelity rules

• Do not collapse the Apple Pay JS and Payment Request platform minimums into one requirement.
• Do not carry the outside-China macOS availability into China.
• Do not interpret sandbox paymentCredentialStatusUnknown as proof of unavailability.
• Do not replace the exact pinned 1.3.8 asset details with reconstructed values.
• Keep each specialized payment request attached to its stated payment shape.
• Keep PKPaymentTokenContext scoped to one token context in a multimerchant payment request.
• Keep the merchant category code optional.