Payments

English

简体中文

English

简体中文

Theme

Apple Pay Session Initialization ​

Apple Pay session initialization is the first step in integrating Apple Pay into your web app. This guide covers loading the Apple Pay JavaScript SDK, detecting availability, and rendering payment buttons.

Overview ​

Apple Pay initialization includes:

  1. Official Demo Experience: Explore Apple's official demo to understand complete functionality
  2. Apple Pay JS SDK Integration: Load Apple's official JavaScript SDK
  3. Availability Detection: Check device and browser support for Apple Pay
  4. Button Rendering: Create and display Apple Pay payment buttons

Official Demo Experience ​

Apple Pay Official Demo Website ​

Apple provides an official Apple Pay Web demo site where you can experience the Apple Pay payment flow on actual devices:

Demo Website Features ​

The demo site showcases:

  • Button Styles: Different types and styles of Apple Pay buttons
  • Payment Flow: Complete payment authorization and processing flow
  • Best Practices: Apple's recommended implementation approaches
  • Code Examples: Reference implementation code

How to Use the Demo ​

  1. Device Requirements:
    • iOS devices (iOS 11.3+) or Mac computers (macOS 10.13+)
    • Access using Safari browser
    • Ensure payment cards are added to Wallet

Adding Payment Cards

Please follow the documentation:

  1. Create Apple Pay sandbox testing accounts
  2. Add test cards (non-mainland regions)
  3. Test cards must be added to the Wallet

If you cannot add test cards, please switch your country/region to non-mainland countries like United States or United Kingdom.

  1. Experience the Demo:

    • Visit the demo site
    • Try different button styles for testing
    • Experience the complete payment authorization flow
    • Observe payment interface and user interactions

  2. Key Observations:

    • Note button rendering effects
    • Observe payment form presentation
    • Understand the complete user authorization flow

Recommendation

Before starting Apple Pay integration, we recommend experiencing the complete flow on the demo site first. This will help you better understand user experience and technical implementation requirements.

Apple Pay JS SDK Integration and Loading ​

Including Apple Pay JavaScript SDK ​

To use Apple Pay in your web app, first include the official JavaScript SDK from Apple's CDN:

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Apple Pay Integration Example</title>
  
  <!-- Include Apple Pay JavaScript SDK -->
  <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
</head>
<body>
  <!-- Your page content -->
</body>
</html>

Important Notes

  • Your website must use HTTPS protocol
  • Recommended to use 1.latest version for latest features and security updates
  • Add crossorigin attribute for cross-origin security

SDK Loading Verification ​

Before using Apple Pay features, verify that the SDK is properly loaded:

javascript
// Check if Apple Pay JavaScript SDK is loaded
if (typeof window.ApplePaySession !== 'undefined') { 
  console.log('Apple Pay SDK loaded successfully');
} else {
  console.log('Apple Pay SDK not loaded or not supported');
}

Apple Pay Availability Detection ​

Basic Availability Check ​

Use the ApplePaySession.canMakePayments() method to detect if the device supports Apple Pay:

javascript
/**
 * Check if Apple Pay is available
 * @returns {boolean} True if Apple Pay is supported
 */
function checkApplePayAvailability() {
  // Check if Apple Pay API is available
  if (!window.ApplePaySession) {
    console.log('Apple Pay API not available');
    return false;
  }

  // Check if device supports Apple Pay
  if (!ApplePaySession.canMakePayments()) { 
    console.log('Device does not support Apple Pay');
    return false;
  }

  console.log('Apple Pay is available');
  return true;
}

// Usage example
if (checkApplePayAvailability()) {
  // Show Apple Pay button
  showApplePayButton();
} else {
  // Show alternative payment methods
  showAlternativePaymentMethods();
}

Best Practice Recommendations ​

For Apple Pay availability detection:

  1. Use Basic Detection: Use canMakePayments() for basic availability detection
  2. Progressive Enhancement: Provide fallback payment methods when Apple Pay is unavailable
  3. User Experience: Avoid over-detection and maintain a clean user interface
javascript
/**
 * Recommended Apple Pay detection approach
 */
function recommendedApplePayCheck() {
  if (window.ApplePaySession && ApplePaySession.canMakePayments()) { 
    // Apple Pay available, show button
    return true;
  }
  // Apple Pay unavailable, use fallback
  return false;
}

Supported Platforms ​

Apple Pay Web is supported on:

  • iOS Devices: iPhone and iPad (iOS 11.3+)
  • macOS Devices: Mac computers (macOS 10.13+, Safari 11.1+)
  • Browser: Safari browser only

Apple Pay Button Introduction and Rendering ​

Using Official Button Element ​

Apple provides an official <apple-pay-button> element that ensures button styling follows design guidelines:

html
<!-- Basic Apple Pay button -->
<apple-pay-button 
  buttonstyle="black" 
  type="buy" 
  locale="en-US">
</apple-pay-button>

Common attributes and references:

AttributeReference
typehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttontype
buttonstylehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttonstyle
localehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttonlocale

Button Style Configuration ​

Customize button appearance using CSS variables:

css
apple-pay-button {
  --apple-pay-button-width: 200px;
  --apple-pay-button-height: 44px;
  --apple-pay-button-border-radius: 8px;
  --apple-pay-button-padding: 0px 16px;
}

For more style options and CSS variables, see: https://developer.apple.com/documentation/applepayontheweb/displaying-apple-pay-buttons-using-javascript.

Complete Button Implementation Example ​

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Apple Pay Button Example</title>
  
  <!-- Include Apple Pay SDK -->
  <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
  
  <style>
    .payment-container {
      max-width: 400px;
      margin: 50px auto;
      padding: 20px;
    }
    
    apple-pay-button {
      --apple-pay-button-width: 100%;
      --apple-pay-button-height: 44px;
      --apple-pay-button-border-radius: 8px;
      margin: 16px 0;
    }
    
    .fallback-button {
      width: 100%;
      height: 44px;
      background-color: #007AFF;
      color: white;
      border: none;
      border-radius: 8px;
      font-size: 16px;
      cursor: pointer;
      display: none;
    }
  </style>
</head>
<body>
  <div class="payment-container">
    <h2>Choose Payment Method</h2>
    
    <!-- Apple Pay button -->
    <apple-pay-button 
      id="apple-pay-button"
      aria-label="Apple Pay"
      buttonstyle="black" 
      type="buy" 
      locale="en-US"
      style="display: none;">
    </apple-pay-button>
    
    <!-- Fallback payment button -->
    <button id="fallback-button" class="fallback-button">
      Pay with Credit Card
    </button>
  </div>

  <script>
    /**
     * Initialize Apple Pay button
     */
    function initializeApplePayButton() {
      const applePayButton = document.getElementById('apple-pay-button');
      const fallbackButton = document.getElementById('fallback-button');
      
      // Check Apple Pay availability
      if (window.ApplePaySession && ApplePaySession.canMakePayments()) { 
        // Show Apple Pay button
        applePayButton.style.display = 'block'; 
        
        // Add click event
        applePayButton.addEventListener('click', () => {
          console.log('Apple Pay button clicked');
          // This chapter covers SDK loading/availability detection/button display only;
          // Session creation covered in "Payment Initiation" section.
        });
      } else {
        // Show fallback payment method
        fallbackButton.style.display = 'block';
        
        fallbackButton.addEventListener('click', () => {
          console.log('Using alternative payment method');
        });
      }
    }
    
    // Initialize after page load
    document.addEventListener('DOMContentLoaded', initializeApplePayButton);
  </script>
</body>
</html>

Chapter Completion Checklist ​

  • Apple Pay JS SDK loaded and verified through loading validation
  • Availability detection using canMakePayments() with appropriate display/fallback behavior
  • <apple-pay-button> rendered and click event bound
  • Fallback payment methods provided (for unavailable scenarios)
  • Understanding: Session creation and session.begin() covered in Payment Initiation

Next Steps ​

After completing Apple Pay initialization, you can continue learning:

  1. Complete Payment Flow: View end-to-end payment flow diagrams and sequence charts
  2. Apple Pay Payment Initiation: Learn how to create payment sessions
  3. Merchant Validation: Configure merchant validation flow
  4. Payment Authorization: Handle payment authorization and completion

Important Reminders

  • Must use HTTPS protocol
  • Only supported in Safari browser
  • Merchant-Owned Account Mode: Requires valid Apple Developer account and certificates
  • Onerway Proxy Mode: No Apple Developer account required