Payments

简体中文

English

简体中文

English

主题

Apple Pay 会话初始化 ​

Apple Pay 会话初始化是在网页中集成 Apple Pay 的第一步，本文档将指导您完成 Apple Pay JavaScript SDK 的引入、可用性检测和按钮渲染。

概览 ​

Apple Pay 初始化包含以下核心步骤：

  1. 官方演示体验：通过 Apple 官方演示了解完整功能
  2. Apple Pay JS SDK 引入：加载 Apple 官方 JavaScript SDK
  3. 可用性检测：检测设备和浏览器对 Apple Pay 的支持
  4. 按钮渲染：创建和显示 Apple Pay 支付按钮

官方演示体验 ​

Apple Pay 官方演示网站 ​

Apple 提供了官方的 Apple Pay Web 演示网站，您可以在实际设备上体验完整的 Apple Pay 支付流程

演示网站功能 ​

该演示网站展示了：

  • 按钮样式：不同类型和样式的 Apple Pay 按钮
  • 支付流程：完整的支付授权和处理流程
  • 最佳实践：Apple 推荐的实现方式
  • 代码示例：可参考的实现代码

如何使用演示 ​

  1. 设备要求：
    • iOS 设备（iOS 11.3+）或 Mac 电脑（macOS 10.13+）
    • 使用 Safari 浏览器访问
    • 确保已在钱包中添加支付卡

添加支付卡注意事项

请按照文档说明：

  1. 创建 Apple Pay 沙盒环境测试账号
  2. 添加非大陆测试卡
  3. 测试卡需添加到钱包中

如果无法添加测试卡，请切换国家为非大陆国家，如美国，英国等

  1. 体验步骤：

    • 访问演示网站
    • 选择不同的按钮样式进行测试
    • 体验完整的支付授权流程
    • 观察支付界面和用户交互

  2. 学习要点：

    • 注意按钮的渲染效果
    • 观察支付表单的展示方式
    • 了解用户授权的完整流程

建议

在开始集成 Apple Pay 之前，建议先在演示网站上体验完整流程，这将帮助您更好地理解用户体验和技术实现要求。

Apple Pay JS SDK 引入与加载 ​

引入 Apple Pay JavaScript SDK ​

要在网页中使用 Apple Pay，首先需要从 Apple CDN 引入官方 JavaScript SDK：

html
<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Apple Pay 集成示例</title>
  
  <!-- 引入 Apple Pay JavaScript SDK -->
  <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
</head>
<body>
  <!-- 您的页面内容 -->
</body>
</html>

重要提示

  • 必须使用 HTTPS 协议访问您的网站
  • 建议使用 1.latest 版本以获得最新功能和安全更新
  • 添加 crossorigin 属性确保跨域安全

SDK 加载验证 ​

在使用 Apple Pay 功能前，验证 SDK 是否正确加载：

javascript
// 检查 Apple Pay JavaScript SDK 是否已加载
if (typeof window.ApplePaySession !== 'undefined') { 
  console.log('Apple Pay SDK 加载成功');
} else {
  console.log('Apple Pay SDK 未加载或不支持');
}

Apple Pay 可用性检测 ​

基础可用性检测 ​

使用 ApplePaySession.canMakePayments() 方法检测设备是否支持 Apple Pay：

javascript
/**
 * 检测 Apple Pay 是否可用
 * @returns {boolean} 如果支持 Apple Pay 则返回 true
 */
function checkApplePayAvailability() {
  // 检查 Apple Pay API 是否可用
  if (!window.ApplePaySession) {
    console.log('Apple Pay API 不可用');
    return false;
  }

  // 检查设备是否支持 Apple Pay
  if (!ApplePaySession.canMakePayments()) { 
    console.log('设备不支持 Apple Pay');
    return false;
  }

  console.log('Apple Pay 可用');
  return true;
}

// 使用示例
if (checkApplePayAvailability()) {
  // 显示 Apple Pay 按钮
  showApplePayButton();
} else {
  // 显示其他支付方式
  showAlternativePaymentMethods();
}

最佳实践建议 ​

对于 Apple Pay 可用性检测，建议：

  1. 使用基础检测：优先使用 canMakePayments() 进行基础可用性检测
  2. 渐进增强：当 Apple Pay 不可用时提供备用支付方式
  3. 用户体验：避免过度检测，保持简洁的用户界面
javascript
/**
 * 推荐的 Apple Pay 检测方式
 */
function recommendedApplePayCheck() {
  if (window.ApplePaySession && ApplePaySession.canMakePayments()) { 
    // Apple Pay 可用，显示按钮
    return true;
  }
  // Apple Pay 不可用，使用备用方案
  return false;
}

支持的平台 ​

Apple Pay Web 支持以下平台：

  • iOS 设备：iPhone 和 iPad（iOS 11.3+）
  • macOS 设备：Mac 电脑（macOS 10.13+，Safari 11.1+）
  • 浏览器：仅支持 Safari 浏览器

Apple Pay 按钮介绍与渲染 ​

使用官方按钮元素 ​

Apple 提供了官方的 <apple-pay-button> 元素，确保按钮样式符合设计规范：

html
<!-- 基础 Apple Pay 按钮 -->
<apple-pay-button 
  buttonstyle="black" 
  type="buy" 
  locale="zh-CN">
</apple-pay-button>

常用属性与官方参考：

属性说明
typehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttontype
buttonstylehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttonstyle
localehttps://developer.apple.com/documentation/applepayontheweb/applepaybuttonlocale

按钮样式配置 ​

通过 CSS 变量自定义按钮外观：

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;
}

更多样式说明与可用 CSS 变量，请参考Apple Pay JavaScript API

完整的按钮实现示例 ​

html
<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Apple Pay 按钮示例</title>

  <!-- 引入 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: 40px auto;
    }

    apple-pay-button {
      --apple-pay-button-width: 100%;
      --apple-pay-button-height: 44px;
      --apple-pay-button-border-radius: 8px;
    }

    .fallback-button {
      display: none;
    }
  </style>
</head>
<body>
  <div class="payment-container">
    <!-- Apple Pay 按钮 -->
    <apple-pay-button
      id="apple-pay-button"
      aria-label="Apple Pay"
      buttonstyle="black"
      type="buy"
      locale="zh-CN"
      style="display: none;">
    </apple-pay-button>

    <!-- 备用支付按钮 -->
    <button id="fallback-button" class="fallback-button">备用支付方式</button>
  </div>

  <script>
    /**
     * 初始化 Apple Pay 按钮
     */
    function initializeApplePayButton() {
      const applePayButton = document.getElementById('apple-pay-button');
      const fallbackButton = document.getElementById('fallback-button');

      // 检查 Apple Pay 可用性
      if (window.ApplePaySession && ApplePaySession.canMakePayments()) { 
        // 显示 Apple Pay 按钮
        applePayButton.style.display = 'block'; 

        // 添加点击事件
        applePayButton.addEventListener('click', () => {
          console.log('Apple Pay 按钮被点击');
          // 本章仅负责 SDK 引入/可用性检测/按钮展示，不创建会话；
          // 创建会话见「支付请求创建」章节。
        });
      } else {
        // 显示备用支付方式
        fallbackButton.style.display = 'block';
      }
    }

    // 页面加载完成后初始化
    document.addEventListener('DOMContentLoaded', initializeApplePayButton);
  </script>
</body>
</html>

本章完成项 Checklist ​

  • 已引入 Apple Pay JS SDK，并通过加载验证
  • 已使用 canMakePayments() 检测可用性并按结果显示/降级
  • 已渲染 <apple-pay-button> 并绑定点击事件
  • 已提供备用支付方式（不可用时降级）
  • 已了解：会话创建与 session.begin() 见支付请求创建

下一步 ​

完成 Apple Pay 初始化后，您可以继续学习：

  1. 完整支付流程：查看端到端支付流程图和时序图
  2. Apple Pay 支付请求创建：了解如何创建支付会话
  3. 商户验证：配置商户验证流程
  4. 支付授权：处理支付授权和完成

重要提醒

  • 必须使用 HTTPS 协议
  • 仅在 Safari 浏览器中支持
  • 商户自有账号模式：需要有效 Apple Developer 账户与证书
  • Onerway 代理模式：不需要 Apple Developer 账户