Apple Pay

Quick Reference

WhatApple Pay

Why生物识别认证一键结账 — 提高转化率、降低欺诈风险、令牌化卡数据

Reading Time15–30 分钟

Difficulty中级

Prerequisites身份验证 → 信用卡

需要激活

Apple Pay 需要按国家、货币和账户进行激活。请联系 tech.services@a55.tech 确认可用性并注册您的商户。

为什么选择 Apple Pay

优势	详情
一键结账	生物识别认证替代手动输入
更高转化率	相比手动卡片表单最高提升 2 倍（典型基准）
更低欺诈率	令牌化 DPAN + 密码学签名
责任转移	钱包认证与发卡机构保护一致
无需存储卡号	真实 PAN 从不被持久化

---

方式 1 — SDK（原生 Apple Pay 按钮）

使用此方式让 A55 SDK 在您的前端处理完整的 Apple Pay 会话。您的后端先创建收款单，SDK 使用 charge_uuid 在 Safari 中原生处理 Apple Pay 支付。

前提条件

• 商户注册： 您的商户必须在 A55 的 Apple Pay 账户中注册。请联系 tech.services@a55.tech。
• 域名关联文件： 在以下路径托管 Apple Pay 域名验证文件：

  https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

  此文件在显示 Apple Pay 按钮的每个域名上都是必需的（Apple Pay on the Web）。

第 1 步——创建收款单（无卡数据）

在您的后端使用 type_charge: "applepay" 创建收款单，但不包含卡字段或 applepay 对象。收款单以 status: "issued" 创建。

请求：

curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "您的_MERCHANT_UUID",
    "wallet_uuid": "您的_WALLET_UUID",
    "payer_name": "John Does",
    "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
    "due_date": "2025-10-31",
    "installment_count": 1,
    "installment_value": 1,
    "currency": "BRL",
    "items": [
      {
        "sku": "CABXIN-HDMI21-2M-BLK",
        "code": "HDMI21-2M-ULTRA",
        "name": "Cabo HDMI 2.1 Ultra 8K 2m – Cabxin",
        "quantity": 1,
        "description": "Cabo HDMI 2.1 (48 Gbps) 支持 8K/60Hz 和 4K/120Hz",
        "unit_amount": 1,
        "total_amount": 1
      }
    ],
    "webhook_url": "https://webhook-test.com/您的端点",
    "type_charge": "applepay"
  }'

响应：

{
  "charge_uuid": "58e6dabd-71fe-49ed-8f55-ec055648dae7",
  "local_currency": 1,
  "currency": "BRL",
  "usd_currency": 0.2,
  "type": "applepay",
  "date": "2026-04-16",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-31",
  "status": "issued",
  "installment_count": 1,
  "charge_payment_url": "https://pay.a55.tech/charge/v2/58e6dabd-71fe-49ed-8f55-ec055648dae7",
  "reference_external_id": "5807d23d-38b4-42c6-97fc-6e68dc6eded0",
  "is_async": false
}

第 2 步——使用 SDK 渲染 Apple Pay 按钮

将第 1 步的 charge_uuid 传入 A55Pay.startApplePay()。SDK 处理 Apple Pay 会话、商户验证、令牌交换以及与收单机构的授权。

<!-- 官方 Apple Pay 按钮（Safari 12.1+） -->
<apple-pay-button
  id="apple-pay-btn"
  buttonstyle="black"
  type="pay"
  locale="zh-CN"
  style="display:none; --apple-pay-button-width:240px; --apple-pay-button-height:44px; --apple-pay-button-border-radius:8px;"
></apple-pay-button>

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk/dist/a55pay-sdk.min.js"></script>
<script>
  var btn = document.getElementById('apple-pay-btn');

  // 仅在 Apple Pay 可用时显示按钮
  if (A55Pay.isApplePayAvailable()) {
    btn.style.display = 'inline-block';
  }

  btn.addEventListener('click', function () {
    A55Pay.startApplePay({
      chargeUuid: '第1步获取的_CHARGE_UUID',
      countryCode: 'CN',
      amount: 1.00,
      currencyCode: 'BRL',            // 默认: 'BRL'
      merchantDomain: 'pay.a55.tech', // 默认: 'pay.a55.tech'
      displayName: '您的公司',          // 默认: 'A55Pay'
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],

      onSuccess: function (result) {
        console.log('支付成功:', result);
        // 跳转到确认页面或更新 UI
      },

      onError: function (error) {
        console.error('支付错误:', error.message);
        // 向用户显示错误信息
      },

      onClose: function () {
        console.log('用户取消了支付');
        // 恢复 UI 至初始状态
      },
    });
  });
</script>

SDK 流程

---

方式 2 — 服务端（已解密数据）

当您的后端已解密 Apple Pay 令牌时，使用此方式。将解密后的卡数据直接发送到 A55 API，在单步内完成创建和授权。

工作原理：

1. 客户在您的前端点击 Apple Pay。
2. Apple 返回加密的支付令牌。
3. 您的后端解密令牌，获得：DPAN（card_number）、有效期、CVV、eci、cavv。
4. 您的后端发送 POST /charge，包含 type_charge: "applepay" 和解密后的字段。
5. A55 同步授权交易并返回结果。

ECI 和 CAVV 为必填项

来自解密 Apple Pay 令牌的 eci 和 cavv 是必填项。缺少或不正确的值会导致拒绝。

切勿记录钱包数据

切勿将原始钱包令牌、cavv 或完整 PAN 记录到分析系统或工单中。

请求

curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "您的_MERCHANT_UUID",
    "wallet_uuid": "您的_WALLET_UUID",
    "payer_name": "John Does",
    "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
    "due_date": "2025-10-31",
    "installment_count": 1,
    "installment_value": 1,
    "currency": "BRL",
    "type_charge": "applepay",
    "card_name": "John Does",
    "card_number": "4111111111111111",
    "card_expiry_year": "2030",
    "card_expiry_month": "08",
    "card_cvv": "123",
    "applepay": {
      "eci": "07",
      "cavv": "AM1mbqehL24XAAa0J04CAoABFA==",
      "type": "credit_card"
    },
    "items": [
      {
        "sku": "CABXIN-HDMI21-2M-BLK",
        "code": "HDMI21-2M-ULTRA",
        "name": "Cabo HDMI 2.1 Ultra 8K 2m – Cabxin",
        "quantity": 1,
        "description": "Cabo HDMI 2.1 (48 Gbps) 支持 8K/60Hz 和 4K/120Hz",
        "unit_amount": 1,
        "total_amount": 1
      }
    ],
    "webhook_url": "https://webhook-test.com/您的端点"
  }'

响应

{
  "charge_uuid": "fe5e2c1e-b3fb-4cc4-bb28-004da37d5804",
  "local_currency": 1,
  "currency": "BRL",
  "usd_currency": 0.2,
  "type": "applepay",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-31",
  "status": "confirmed",
  "message": [],
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "e4e3ec12-b51a-4ea2-aceb-2b41602a5a84",
  "is_async": false
}

---

状态生命周期

状态	描述
issued	收款单已创建，等待 Apple Pay SDK 处理（仅方式 1）
confirmed	授权成功
paid	已确认待结算
error	被拒绝或失败

SDK V2 →A55Pay.startApplePay() 及其他 SDK 方法H2H →卡和钱包集成模式网络令牌 →DPAN 和密码学签名流程创建收款单 →完整的收款单 Schema