Antom, leading provider of tailored payment solutions

Web/Wap

此章节为您提供  Web/Wap 端卡支付 SDK 的集成指南,帮助您快速开始电脑浏览器及手机浏览器内的支付相关页面渲染。

集成准备

在您开始集成前,请阅读 集成指南 及 API 概述 文档,了解服务端 API 的集成步骤及 API 的调用注意事项,并确保已完成以下预配置及环境准备工作:

  • 在 开发者中心 已获得 client ID
  • 在 开发者中心 已完成密钥配置
  • 已安装 npm
  • 兼容性问题处理:对于 IE 系列浏览器或其他低版本浏览器,需要提供相应的 Polyfill 支持,在项目构建时,建议使用 babel-preset-env 来解决浏览器兼容问题。
  • 请使用建议的系统版本:
    • 手机浏览器:
      • 确保 iOS 9 及以上版本
      • 确保 Android 5.0 及以上
    • 电脑浏览器:推荐使用的浏览器版本如下 : 

 

Edge

 

Firefox

 Last 2 versions

Chrome

 Last 2 versions

Safari

 Last 2 versions

Opera

 Last 2 versions

Electron

 Last 2 versions

关键集成步骤

请根据以下步骤完成集成:

1

引入 SDK 包。

商户客户端

您可以通过以下任意一种方式,在项目中引入 SDK 包:

  • 通过 npm 包管理器在项目中引入 SDK 包:在命令行中输入安装命令即可完成引入。
  • 使用 CDN 资源,在 HTML 文件中使用右侧 script 标签即可完成引入。
通过 npm 引入 SDK 包:
bash
npm install @alipay/ams-checkout
使用 CDN 资源引入 SDK 包:
markup
<script src="https://sdk.marmot-cloud.com/package/ams-checkout/1.0.5/umd/index.min.js"></script>
2

通过 AMSCheckout()构造函数创建 SDK 实例:

商户客户端
  • 创建 config 对象:必传,Object 类型。包含所有配置参数:
    • locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器多语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值,如果传入的值不是以下四种,将提供英语页面:
      • en_US:英语
      • pt_BR:葡萄牙语
      • ko_KR:韩语
      • es_ES:西班牙语
    • environment: 必传,String 类型。用于传入环境参数,支持的值包括:
      • sandbox:沙箱环境
      • prod:生产环境
    • mode:必传,String 类型,用于指定收银台展示模式,支持的值包括:
      • component:此模式用于在您的应用中展示预构建的支付方式组件。
    • networkMode:必传,String 类型,用于指定网络模式,支持的值包括:​
      • session:此模式下,您的服务端仅需发送一次请求(即 支付会话创建 请求),支付数据在您的前端与Alipay服务器间进行通信。
    • analytics:选传,Object 类型,用于配置分析数据服务,包含以下参数:
      • enabled: 选传,Boolean 类型。默认值为 true ,代表允许 SDK 上传分析运行数据以提供更好的服务。如您不允许上传分析运行数据,需指定此值为 false 。
    • onLog(): 选传,输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。
    • onEventCallback(): 选传,输出 SDK 运行期间支付发生异常时的结束事件,例如支付失败、3D 验证失败等。
  • 实例化 AMSCheckout 。
获取浏览器语言的代码示例
javascript
let language = navigator.language || navigator.userLanguage;
language = language.replace("-", "_"); // 将 "-" 替换成 "_"
以下示例分别针对 npm 引包方式和 CDN 引包方式展示创建 SDK 实例的代码示例:
javascript
import { AMSCheckout } from '@alipay/ams-checkout' // 包管理

const checkoutApp = new AMSCheckout({
  environment: "sandbox",
  locale: "en_US",
  mode: "component",
  networkMode: "session",
  analytics: {
    enabled: true
  },
  onLog: ({code, message})=>{},
  onEventCallback: ({code, message})=>{}
});
3

向 Alipay 服务器发起 支付会话创建 请求。

商户服务端

买家在支付方式选择页选择卡支付方式后,商户客户端自行实现支付按钮的点击事件监听。当监听到支付按钮被用户点击后,商户服务端需向 Alipay 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后,将响应中的 paymentSessionData 参数值用于步骤 4 。

以下支付会话创建请求示例,仅包含了必传字段及部分选传字段:
json
{
  "order": {
    "buyer": {
      "buyerName": {
        "firstName": "*****",
        "fullName": "D***u",
        "lastName": "Liu",
        "middleName": "Skr"
      },
      "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
      "referenceBuyerId": "tony.c"
    },
    "goods": [{
      "goodsBrand": "AMSDM",
      "goodsCategory": "card/ssr/adc",
      "goodsName": "Goods No.1",
      "goodsQuantity": "1",
      "goodsSkuName": "SKU1",
      "goodsUnitAmount": {
        "currency": "USD",
        "value": "10000"
      },
      "goodsUrl": "HangZhou LeiFenTa",
      "referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
    }],
    "orderAmount": {
      "currency": "BRL",
      "value": "2129"
    },
    "orderDescription": "AMSDM_GIFT",
    "referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
  },
  "paymentAmount": {
    "currency": "BRL",
    "value": "2129"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodType": "CARD",
    "paymentMethodMetaData":{
        "paymentMethodRegion":"BR"
    }
  },
  "paymentNotifyUrl": "https://www.google.com.sg",
  "paymentRedirectUrl": "https://www.baidu.com",
  "paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
  "productCode": "CASHIER_PAYMENT",
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "enableInstallmentCollection":"true"
}
支付会话创建请求的响应示例:
json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
4

使用实例对象中的 createComponent() 函数创建支付要素收集组件:

商户客户端
  • 使用 paymentSessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 paymentSessionData 参数。
  • 调用实例对象中的 createComponent()函数,返回值为 Promise, 内容为组件实例对象。支付区块 DOM 节点即可根据环境参数渲染出卡支付方式视图并插入当前页面中。
调用 createComponent()
javascript
async function create(paymentSessionData) {
  await checkoutApp.createComponent('card', { paymentSessionData });
}
参考信息
事件码

SDK 提供的事件码如下:

  • SDK_INTERNAL_ERROR:此事件码代表以下事件信息中的一种情况:

    • 服务端返回的数据不符合 JSON 格式,请联系技术支持。

    • 浏览器不支持 postMessage 通信模式, 需更换或者升级浏览器。

    • 无法创建 iFrame 元素,需更换或升级浏览器,或者尝试重试。

  • SDK_INIT_PARAMETER_ERROR:此事件码代表以下事件信息中的一种情况:

    • 初始化时传入的环境信息有误,需检查 environment 参数的值。

    • 初始化时传入的模式信息有误,需检查 mode 参数的值。

    • 初始化时传入的语言信息有误,需检查 locale 参数的值。

    • 初始化时传入的网络模式有误,需检查 networkMode 参数的值。

    • 初始化时传入的 onLog() 有误,需检查 onLog() 是否是一个函数。

  • SDK_CREATECOMPONENT_ERROR:创建卡组件失败,需使用正确参数再次调用 createComponent()。

集成代码关键步骤示例

以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例,需要您自行处理服务端接口的调用。

javascript
import { AMSCheckout } from "@alipay/ams-checkout";
// 步骤一:实例化sdk
const checkoutApp = new AMSCheckout({
  mode: "component",
  locale: "en_US",
  environment: "sandbox",
  networkMode: "session",
  onLog: () => {},
  onEventCallback: () => {},
});
// 处理卡支付按钮事件
document
  .querySelector("#你的表单id")
  .addEventListener("submit", handleSubmit);

async function handleSubmit() {
  // 步骤二:服务端创建调用支付会话接口,获取paymentSessionData
  async function getPaymentSessionData() {
    const url = "填写服务端地址";
    const config = {
      // 填写请求配置
    };
    const response = await fetch(url, config);
    // 获取响应中的paymentSessionData参数值
    const { paymentSessionData } = await response.json();
    return paymentSessionData;
  }
  const paymentSessionData = await getPaymentSessionData();

  // 步骤三:创建渲染卡组件
  // 最佳实践
  const card = await checkoutApp.createComponent("card", {
    paymentSessionData,
  });
}