Payments

简体中文

English

简体中文

English

主题

Apple Pay 支付请求创建 ​

支付请求创建发生在用户点击 Apple Pay 按钮时，创建支付会话并显示 Apple Pay 支付表单。

对接概览 ​

支付请求创建过程包括：

  1. 用户点击 Apple Pay 按钮 → 触发支付会话创建
  2. 创建支付请求 → 定义支付参数和金额
  3. 初始化 ApplePaySession → 启动 Apple Pay 流程
  4. 显示支付表单 → 向用户展示 Apple Pay 界面

查看完整支付流程了解详细时序图。

支付请求参数 ​

必需参数 ​

支付请求必须包含这些基本参数：

javascript
const paymentRequest = {
  // 基础配置（从 Onerway 查询可用支付方式接口获取）
  countryCode: config.countryCode,        // 从 Onerway 配置获取
  currencyCode: 'USD',                    // 支付货币
  supportedNetworks: config.subCardTypes.map(card => card.toLowerCase()),  // 从 Onerway 配置获取
  merchantCapabilities: ['supports3DS'],
  
  // 支付总额
  total: {
    label: '您的商店名称',
    amount: '29.99',                      // 字符串，两位精度
    type: 'final'
  }
};

从 Onerway 获取配置

要获取必需的 countryCode 和 supportedNetworks 配置，请使用 Onerway 的支付方式查询接口。此接口返回您商户账户所需的 Apple Pay 配置，确保显示正确的支持卡类型和地区设置。

可选参数 ​

添加这些参数实现增强功能：

javascript
// 订单明细（推荐使用，增强透明度）
lineItems: [
  { label: '商品', amount: '24.99', type: 'final' },
  { label: '配送费', amount: '5.00', type: 'final' }
],

// 配送信息收集
requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'],
shippingMethods: [
  {
    label: '标准配送',
    amount: '5.00',
    detail: '5-7 个工作日',
    identifier: 'standard'
  }
],
shippingType: 'shipping',

// 账单信息收集
requiredBillingContactFields: ['postalAddress', 'name'],

// 订阅支付
recurringPaymentRequest: {
  paymentDescription: '月度订阅服务',
  regularBilling: {
    label: '月费',
    amount: '9.99',
    type: 'final',
    paymentTiming: 'recurring',
    recurringPaymentIntervalUnit: 'month',
    recurringPaymentIntervalCount: 1,
    recurringPaymentStartDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString() // 7天试用期后开始
  },
  trialBilling: {
    label: '7天免费试用',
    amount: '0.00',
    type: 'final',
    paymentTiming: 'immediate' // 立即开始
  },
  managementURL: 'https://your-website.com/manage-subscription' // 订阅管理页面
}

Apple Pay 参数文档

更多参数配置详情，请参考 Apple 官方文档：

基础对接实现 ​

1. 获取 Onerway 配置并创建支付会话 ​

配置获取说明

使用 支付方式查询接口 获取 Apple Pay 所需的配置信息，包括 countryCode 和 supportedNetworks。

javascript
/**
 * 获取 Onerway Apple Pay 配置
 * @returns {Promise<Object>} Apple Pay 配置对象
 */
async function getOnerwayConfig() {
  const response = await fetch('/api/onerway/payment-methods', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      merchantId: 'your-merchant-id',
      paymentMethod: 'APPLE_PAY'
    })
  });
  
  if (!response.ok) {
    throw new Error(`配置获取失败: ${response.status}`);
  }
  
  return response.json();
}

/**
 * 创建 Apple Pay 支付请求
 * @param {Object} config - Onerway 配置
 * @param {string} orderTotal - 订单总额
 * @param {Array} orderItems - 订单明细
 * @returns {Object} Apple Pay 支付请求对象
 */
function createPaymentRequest(config, orderTotal, orderItems) {
  return {
    countryCode: config.countryCode,           // 来自 Onerway
    currencyCode: 'USD',
    supportedNetworks: config.subCardTypes.map(card => card.toLowerCase()), // 来自 Onerway
    merchantCapabilities: ['supports3DS'],
    total: {
      label: '您的商店名称',                    // 您的商户显示名称
      amount: orderTotal.toString(),           // 字符串，两位精度
      type: 'final'
    },
    lineItems: orderItems
  };
}

/**
 * 启动 Apple Pay 支付流程
 * @param {string} orderTotal - 订单总额
 * @param {Array} orderItems - 订单明细
 */
async function startApplePayPayment(orderTotal, orderItems) {
  try {
    // 第一步：获取 Onerway 配置
    const config = await getOnerwayConfig();
    
    // 第二步：创建支付请求
    const paymentRequest = createPaymentRequest(config, orderTotal, orderItems);

    // 第三步：创建并启动会话（本章首次创建 ApplePaySession 并 begin()）
    const session = new ApplePaySession(3, paymentRequest); 
    setupEventHandlers(session, config);
    session.begin(); 
    
  } catch (error) {
    console.error('启动 Apple Pay 失败:', error);
    handlePaymentError(error);
  }
}

/**
 * 处理支付启动错误
 * @param {Error} error - 错误对象
 */
function handlePaymentError(error) {
  // 根据错误类型提供不同的用户提示
  if (error.message.includes('配置获取失败')) {
    alert('支付配置加载失败，请稍后重试');
  } else {
    alert('无法启动 Apple Pay，请重试或选择其他支付方式');
  }
}

Apple Pay 会话文档

详细的会话创建和配置，请参考：

2. 事件处理器设置 ​

Apple Pay 会话需要事件处理器来处理商户验证和支付处理。设置基本的事件结构：

javascript
/**
 * 设置 Apple Pay 会话事件处理器
 * @param {ApplePaySession} session - Apple Pay 会话
 * @param {Object} config - 商户/Onerway 配置，用于商户验证阶段
 */
function setupEventHandlers(session, config) {
  // 商户验证 - 详细实现请参考商户验证指南
  session.onvalidatemerchant = (event) => { 
    handleMerchantValidation(session, event, config);
  };

  // 支付授权 - 详细实现请参考支付授权指南
  session.onpaymentauthorized = (event) => { 
    handlePaymentAuthorization(event);
  };

  // 用户取消
  session.oncancel = (event) => {
    console.log('用户取消了 Apple Pay');
    // 清理任何待处理的流程
  };
}

事件处理器实现

商户验证和支付授权的实际实现涉及复杂的逻辑。详细指南请参考：

Apple Pay 事件文档

事件处理详细说明：

完整的按钮点击处理器 ​

集成 Onerway 的完整实现 ​

javascript
/**
 * 检查设备对 Apple Pay 的支持
 * @returns {boolean} 是否支持 Apple Pay
 */
function checkDeviceSupport() {
  if (!ApplePaySession.canMakePayments()) {
    alert('此设备不支持 Apple Pay');
    return false;
  }
  return true;
}

/**
 * 获取当前订单数据
 * @returns {Object} 订单数据对象
 */
function getCurrentOrderData() {
  // 示例订单数据，实际项目中应从页面或状态管理中获取
  return {
    total: '29.99',
    currencyCode: 'USD',
    items: [
      { label: '商品', amount: '24.99', type: 'final' },
      { label: '配送费', amount: '5.00', type: 'final' }
    ]
  };
}

/**
 * 完整的 Apple Pay 按钮点击处理器
 */
async function handleApplePayButtonClick() {
  // 第一步：检查设备支持
  if (!checkDeviceSupport()) {
    return;
  }

  try {
    // 第二步：获取 Onerway 配置（复用之前定义的函数）
    const config = await getOnerwayConfig();

    // 第三步：获取当前订单数据
    const orderData = getCurrentOrderData();

    // 第四步：创建支付请求（复用之前定义的函数）
    const paymentRequest = createPaymentRequest(config, orderData.total, orderData.items);
    
    // 更新货币代码为订单货币
    paymentRequest.currencyCode = orderData.currencyCode;

    // 第五步：启动支付会话
    const session = new ApplePaySession(3, paymentRequest); 
    setupEventHandlers(session, config);  // 包含 Onerway 集成逻辑
    session.begin(); 

  } catch (error) {
    console.error('启动 Apple Pay 失败:', error);
    handlePaymentError(error);
  }
}

Onerway 接口文档

相关 Onerway API 接口：

  • 支付方式查询接口 - 获取 countryCode、supportedNetworks 等配置
  • 商户验证接口 - 处理 Apple Pay 商户验证请求
  • 支付处理接口 - 处理 Apple Pay 支付令牌

常见问题与解决方案 ​

设备支持问题 ​

问题：Apple Pay 按钮不显示
原因：设备或浏览器不支持 Apple Pay
解决方案：

javascript
// 检查设备支持并提供备用方案
if (ApplePaySession && ApplePaySession.canMakePayments()) { 
  document.getElementById('apple-pay-button').style.display = 'block';
} else {
  document.getElementById('fallback-payment').style.display = 'block'; 
  console.log('Apple Pay 不可用，已显示备用支付方式');
}

配置错误问题 ​

问题：收到 "商户配置无效" 错误
原因：Onerway 配置信息不完整或不正确
解决方案：验证从支付方式查询接口获取的配置：

javascript
// 验证必要的配置项
function validateConfig(config) {
  const required = ['countryCode', 'subCardTypes'];
  for (const field of required) {
    if (!config[field]) {
      throw new Error(`缺少必要配置: ${field}`);
    }
  }
  
  if (!Array.isArray(config.subCardTypes) || config.subCardTypes.length === 0) {
    throw new Error('supportedNetworks 配置无效');
  }
}

金额格式问题 ​

问题：支付金额被 Apple Pay 拒绝
原因：金额格式不正确
解决方案：确保金额为字符串格式且精度正确：

javascript
// 正确的金额格式
function formatAmount(amount) {
  return Number(amount).toFixed(2).toString();
}

// 使用示例
total: { 
  amount: formatAmount(orderTotal),  // "29.99"
  type: 'final'
}

// 错误：不要直接传递数字
// total: { amount: 29.99 }

下一步 ​

实现支付请求创建后，继续完善您的 Apple Pay 集成：

  1. 商户验证：了解如何处理 onvalidatemerchant 事件和证书管理
  2. 支付授权：了解如何处理 onpaymentauthorized 事件和支付处理
  3. 完整支付流程：查看包含 Onerway 集成的完整时序图
  4. Onerway 支付接口：查看支付处理的详细 API 文档

前置步骤回顾 ​

如果您还未完成前期配置，请先参考：

本章完成项 Checklist ​

完成本章后，您应该已经实现以下功能：

  • 已从 Onerway 获取 Apple Pay 配置（countryCode、supportedNetworks）
  • 已创建 paymentRequest 对象并配置必需参数（total、currencyCode等）
  • 已实现 ApplePaySession 创建和 session.begin() 调用
  • 已设置事件处理器结构（onvalidatemerchant、onpaymentauthorized、oncancel）
  • 已添加设备支持检查和错误处理
  • 已实现完整的按钮点击处理器流程

关键要求 ​

对接检查清单

  • ✅ 域名已启用 HTTPS
  • ✅ 已从 Onerway 获取 Apple Pay 配置
  • ✅ 已实现 onvalidatemerchant 和 onpaymentauthorized 事件处理器
  • ✅ 已添加不支持设备的错误处理
  • ✅ 后端已准备好商户验证和支付处理集成