A55Pay SDK 参考文档 (V2)

Quick Reference

WhatA55Pay JavaScript SDK V2 完整参考

Why使用浏览器端 SDK 集成银行卡支付、托管结账和 Apple Pay

Reading Time25 min

DifficultyIntermediate

Prerequisites身份验证 → 创建扣款

A55Pay JavaScript SDK V2 在买家浏览器中运行：收集卡数据、执行设备数据采集 (DDC)、处理 3DS 身份验证、处理支付并触发回调。原始卡数据不会经过您的源服务器。

---

前置条件

在调用任何 SDK 方法之前，您的后端必须创建一笔不含卡数据的扣款。将返回的 charge_uuid 传递给前端。

创建扣款 →

对于 Apple Pay，创建 type_charge: "applepay" 的扣款。对于托管结账，使用 创建结账 并将 checkout_uuid 传递给 A55Pay.open()。

---

安装

最新版本：

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>

固定版本（生产环境推荐）：

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@4.0.8/dist/a55pay-sdk.min.js"></script>

加载后，SDK 作为 window.A55Pay 全局可用。

版本固定

在生产环境中固定特定版本（如 a55pay-sdk@4.0.8），以确保部署行为一致。

---

属性

A55Pay.VERSION

返回当前 SDK 版本。

console.log(A55Pay.VERSION); // "4.0.8"

---

方法

A55Pay.payV2(config)

处理信用卡/借记卡支付，自动收集设备信息，支持 CyberSource 身份验证和 3DS。

参数

字段	类型	必填	说明
charge_uuid	string	是	通过 A55 API 创建的扣款 UUID
userData	object	是	付款人和卡数据（见下文）
onSuccess	function	否	成功回调
onError	function	否	错误回调
onReady	function	否	SDK 准备就绪时触发

userData 字段

字段	类型	必填	说明
payer_name	string	是	付款人全名
payer_email	string	是	付款人邮箱
payer_tax_id	string	否	税号（巴西 CPF/CNPJ）
cell_phone	string	否	手机号码
holder_name	string	是	卡面姓名
number	string	是	卡号
expiry_month	string	是	有效期月份（如 "12"）
expiry_year	string	是	有效期年份（如 "2028"）
ccv	string	条件	卡 CVV（无 card_cryptogram 时必填）
card_token	string	否	已保存的卡令牌
card_cryptogram	string	条件	卡密码文（无 ccv 时必填）
postal_code	string	是	账单邮编
street	string	是	账单街道
address_number	string	否	门牌号（默认："n/d"）
complement	string	否	地址补充
neighborhood	string	否	街区（默认："n/d"）
city	string	是	城市
state	string	是	州/省代码
country	string	是	国家（ISO alpha-2，如 "BR"）
shipping_postal_code	string	否	收货邮编（省略时使用账单地址）
shipping_street	string	否	收货街道
shipping_address_number	string	否	收货门牌号
shipping_complement	string	否	收货地址补充
shipping_neighborhood	string	否	收货街区
shipping_city	string	否	收货城市
shipping_state	string	否	收货州/省
shipping_country	string	否	收货国家

示例

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>
<script>
  document.getElementById('pay-btn').addEventListener('click', function() {
    A55Pay.payV2({
      charge_uuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      userData: {
        payer_name: 'Joao da Silva',
        payer_email: 'joao@email.com',
        payer_tax_id: '12345678900',
        cell_phone: '11999998888',
        holder_name: 'JOAO DA SILVA',
        number: '4111 1111 1111 1111',
        expiry_month: '12',
        expiry_year: '2028',
        ccv: '123',
        postal_code: '01310-100',
        street: 'Av Paulista',
        address_number: '1000',
        complement: 'Sala 1',
        neighborhood: 'Bela Vista',
        city: 'Sao Paulo',
        state: 'SP',
        country: 'BR'
      },
      onReady: function() {
        console.log('SDK ready to process');
      },
      onSuccess: function(result) {
        console.log('Payment approved:', result);
        // result.status = 'confirmed' | 'paid' | 'pending'
        // result.charge_uuid
        // result.data (完整扣款数据)
        // result.threeds_completed (3DS 完成时为 true)
      },
      onError: function(error) {
        console.error('Payment error:', error.message);
      }
    });
  });
</script>

内部流程

---

A55Pay.authentication(config)

独立的 CyberSource 设备数据采集 (DDC)。由 payV2 内部调用，也可单独调用。

参数

字段	类型	必填	说明
transactionReference	string	是	扣款 UUID
cardBrand	string	是	卡品牌（见下方值）
cardExpiryMonth	string	是	有效期月份
cardExpiryYear	string	是	有效期年份
cardNumber	string	是	卡号（无空格）
onSuccess	function	否	成功回调
onError	function	否	错误回调

cardBrand 有效值： Visa、MasterCard、AmericanExpress、Discover、JCB、DinersClub、Hipercard、Elo

示例

A55Pay.authentication({
  transactionReference: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  cardBrand: 'Visa',
  cardExpiryMonth: '12',
  cardExpiryYear: '2028',
  cardNumber: '4111111111111111',
  onSuccess: function(result) {
    console.log('Session ID:', result.sessionId);
    console.log('Reference ID:', result.referenceId);
    // result.accessToken
    // result.deviceDataCollection
  },
  onError: function(error) {
    console.error('Authentication failed:', error.message);
  }
});

---

A55Pay.getDeviceId()

返回通过 ThreatMetrix 生成的当前设备 ID。SDK 加载时自动生成。

var deviceId = A55Pay.getDeviceId();
console.log(deviceId); // "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5"

---

A55Pay.regenerateDeviceId()

强制生成新的设备 ID 并重新加载 ThreatMetrix 脚本。

var newDeviceId = A55Pay.regenerateDeviceId();
console.log('New device ID:', newDeviceId);

---

A55Pay.open(config)

在模态 iframe 或嵌入式容器中打开 A55 结账 (v2)，通过 postMessage 通信。

参数

字段	类型	必填	说明
checkoutUuid	string	是	结账 UUID
display	'modal' | 'embed'	否	显示模式（默认：'modal'）
containerId	string	否	嵌入模式的 HTML 元素 ID（缺失时自动创建）
onEvent	function	否	通用结账事件回调
onSuccess	function	否	支付确认时触发
onClose	function	否	结账关闭时触发
onError	function	否	错误回调

返回值

返回带有 close() 方法的对象，用于以编程方式关闭结账。

模态示例

var instance = A55Pay.open({
  checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  display: 'modal',
  onSuccess: function(data) {
    console.log('Payment confirmed:', data);
    // data.status = 'paid' | 'confirmed'
    // data.chargeUuid
  },
  onError: function(err) {
    console.error('Error:', err.message);
  },
  onClose: function() {
    console.log('Checkout closed');
  },
  onEvent: function(event) {
    console.log('Event received:', event);
  }
});

// 以编程方式关闭：
// instance.close();

嵌入示例

<div id="my-checkout" style="min-height:600px;"></div>

<script>
  A55Pay.open({
    checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    display: 'embed',
    containerId: 'my-checkout',
    onSuccess: function(data) {
      console.log('Payment confirmed:', data);
    },
    onClose: function() {
      console.log('Checkout closed');
    }
  });
</script>

---

A55Pay.isApplePayAvailable()

同步检查当前浏览器和设备是否支持 Apple Pay。

if (A55Pay.isApplePayAvailable()) {
  document.getElementById('apple-pay-btn').style.display = 'block';
} else {
  console.log('Apple Pay not available');
}

---

A55Pay.startApplePay(config)

启动 Apple Pay 支付。必须在点击事件处理程序中调用（需要用户手势）。

需要激活

Apple Pay 需要事先在 A55 的 Apple Pay 账户中注册商户并托管域名验证文件。集成前请联系 tech.services@a55.tech。

参数

字段	类型	必填	说明
chargeUuid	string	是	使用 type_charge: "applepay" 创建的扣款 UUID
countryCode	string	是	ISO 3166-1 alpha-2 国家代码（如 'BR'）
amount	string	是	支付金额（如 '150.00'）
currencyCode	string	否	ISO 4217 货币代码（默认：'BRL'）
merchantDomain	string	否	商户域名（默认：'pay.a55.tech'）
displayName	string	否	支付表单显示名称（默认：'A55Pay'）
supportedNetworks	string[]	否	支持的网络（默认：['visa', 'masterCard', 'elo', 'amex']）
onSuccess	function	否	成功回调
onError	function	否	错误回调
onClose	function	否	用户取消支付表单时触发

示例

<button id="apple-pay-btn" style="display:none;">Pay with Apple Pay</button>

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

  if (A55Pay.isApplePayAvailable()) {
    btn.style.display = 'inline-block';
  }

  btn.addEventListener('click', function() {
    A55Pay.startApplePay({
      chargeUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      countryCode: 'BR',
      amount: '150.00',
      currencyCode: 'BRL',
      displayName: 'My Store',
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],
      onSuccess: function(result) {
        console.log('Apple Pay approved:', result);
      },
      onError: function(error) {
        console.error('Apple Pay error:', error.message);
      },
      onClose: function() {
        console.log('User cancelled Apple Pay');
      }
    });
  });
</script>

Apple Pay 流程

Apple Pay 要求

• 必须使用 HTTPS（HTTP 不可用）
• Safari（macOS/iOS）或带 WebKit 的 iOS 浏览器
• Apple Wallet 中已配置银行卡
• 在 Apple Developer Portal 中验证域名

完整 Apple Pay 文档 →

---

完整 HTML 示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>A55Pay SDK 示例</title>
</head>
<body>
  <h1>使用 A55Pay 支付</h1>

  <form id="payment-form">
    <input type="text" id="holder" placeholder="卡面姓名" />
    <input type="text" id="card-number" placeholder="卡号" />
    <input type="text" id="expiry-month" placeholder="MM" />
    <input type="text" id="expiry-year" placeholder="YYYY" />
    <input type="text" id="cvv" placeholder="CVV" />
    <input type="text" id="email" placeholder="邮箱" />
    <input type="text" id="name" placeholder="全名" />
    <button type="submit">银行卡支付</button>
  </form>

  <button id="apple-pay-btn" style="display:none;background:#000;color:#fff;padding:12px 24px;border:none;border-radius:8px;font-size:16px;cursor:pointer;">
    Apple Pay 支付
  </button>

  <button id="open-checkout-btn">打开 A55 结账</button>

  <div id="result"></div>

  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>
  <script>
    var CHARGE_UUID = 'YOUR_CHARGE_UUID_HERE';
    var resultDiv = document.getElementById('result');

    function showResult(msg) {
      resultDiv.textContent = msg;
    }

    document.getElementById('payment-form').addEventListener('submit', function(e) {
      e.preventDefault();

      A55Pay.payV2({
        charge_uuid: CHARGE_UUID,
        userData: {
          payer_name: document.getElementById('name').value,
          payer_email: document.getElementById('email').value,
          holder_name: document.getElementById('holder').value,
          number: document.getElementById('card-number').value,
          expiry_month: document.getElementById('expiry-month').value,
          expiry_year: document.getElementById('expiry-year').value,
          ccv: document.getElementById('cvv').value,
          postal_code: '01310100',
          street: 'Av Paulista',
          city: 'Sao Paulo',
          state: 'SP',
          country: 'BR'
        },
        onSuccess: function(result) {
          showResult('Payment approved! Status: ' + result.status);
        },
        onError: function(error) {
          showResult('Error: ' + error.message);
        }
      });
    });

    if (A55Pay.isApplePayAvailable()) {
      document.getElementById('apple-pay-btn').style.display = 'inline-block';
    }

    document.getElementById('apple-pay-btn').addEventListener('click', function() {
      A55Pay.startApplePay({
        chargeUuid: CHARGE_UUID,
        countryCode: 'BR',
        amount: '100.00',
        currencyCode: 'BRL',
        displayName: 'My Store',
        onSuccess: function(result) {
          showResult('Apple Pay approved!');
        },
        onError: function(error) {
          showResult('Apple Pay error: ' + error.message);
        },
        onClose: function() {
          showResult('Apple Pay cancelled');
        }
      });
    });

    document.getElementById('open-checkout-btn').addEventListener('click', function() {
      A55Pay.open({
        checkoutUuid: CHARGE_UUID,
        display: 'modal',
        onSuccess: function(data) {
          showResult('Checkout confirmed! Status: ' + data.status);
        },
        onError: function(err) {
          showResult('Checkout error: ' + err.message);
        },
        onClose: function() {
          showResult('Checkout closed');
        }
      });
    });

    console.log('A55Pay SDK v' + A55Pay.VERSION);
    console.log('Device ID:', A55Pay.getDeviceId());
  </script>
</body>
</html>

---

常见错误

错误	原因	解决方案
Missing charge_uuid or userData	缺少必填参数	确保提供了 charge_uuid 和 userData
payer_name and payer_email are required	缺少付款人数据	在 userData 中包含 payer_name 和 payer_email
Either ccv or card_cryptogram is required	无卡身份验证方式	发送 ccv 或 card_cryptogram
Apple Pay is not available	浏览器不支持 Apple Pay	在 macOS/iOS Safari 中使用，且 Wallet 中有卡
Must create ApplePaySession from user gesture	startApplePay 在点击处理程序外调用	仅在 addEventListener('click', ...) 内调用
Invalid countryCode	格式错误	使用大写 ISO 3166-1 alpha-2（如 "BR"）
Invalid amount	非数字值	发送数字字符串（如 "150.00"）
An Apple Pay session is already in progress	重复点击	处理期间禁用按钮

---

安全说明

• SDK 不存储卡数据 — 直接发送到 A55 后端
• 设备 ID 通过 ThreatMetrix 生成，用于欺诈检测
• 3DS 2.0 通过 CyberSource 自动处理
• Apple Pay 令牌端到端加密
• 所有通信使用 HTTPS
• 结账 postMessage 按来源过滤（pay.a55.tech）

日志记录

切勿在回调中记录 PAN、CVV 或密码文。SDK 在浏览器上下文中处理卡数据 — 请保持在此范围内。

---

使用沙盒卡测试

Card Number	Brand	Scenario	Expected Status
4111 1111 1111 1111	Visa	支付成功	confirmed
5500 0000 0000 0004	Mastercard	支付成功	confirmed
4000 0000 0000 0002	Visa	卡被拒绝	declined
4000 0000 0000 0101	Visa	需要 3DS 挑战	confirmed
4000 0000 0000 0069	Visa	处理错误	error

---

3D Secure →A55 的 3DS 身份验证工作原理。DataOnly →通过数据共享获得最高批准率。结账页面 →托管重定向 — 您的网站零卡数据。