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 包:
1npm install @alipay/ams-checkout
使用 CDN 资源引入 SDK 包：
1<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 。
获取浏览器语言的代码示例
1let language = navigator.language || navigator.userLanguage;
2language = language.replace("-", "_"); // 将 "-" 替换成 "_"
以下示例分别针对 npm 引包方式和 CDN 引包方式展示创建 SDK 实例的代码示例：
1import { AMSCheckout } from '@alipay/ams-checkout' // 包管理
2
3const checkoutApp = new AMSCheckout({
4  environment: "sandbox",
5  locale: "en_US",
6  mode: "component",
7  networkMode: "session",
8  analytics: {
9    enabled: true
10  },
11  onLog: ({code, message})=>{},
12  onEventCallback: ({code, message})=>{}
13});
3

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

商户服务端

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

以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：
1{
2  "order": {
3    "buyer": {
4      "buyerName": {
5        "firstName": "*****",
6        "fullName": "D***u",
7        "lastName": "Liu",
8        "middleName": "Skr"
9      },
10      "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
11      "referenceBuyerId": "tony.c"
12    },
13    "goods": [{
14      "goodsBrand": "AMSDM",
15      "goodsCategory": "card/ssr/adc",
16      "goodsName": "Goods No.1",
17      "goodsQuantity": "1",
18      "goodsSkuName": "SKU1",
19      "goodsUnitAmount": {
20        "currency": "USD",
21        "value": "10000"
22      },
23      "goodsUrl": "HangZhou LeiFenTa",
24      "referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
25    }],
26    "orderAmount": {
27      "currency": "BRL",
28      "value": "2129"
29    },
30    "orderDescription": "AMSDM_GIFT",
31    "referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
32  },
33  "paymentAmount": {
34    "currency": "BRL",
35    "value": "2129"
36  },
37  "paymentFactor": {
38    "isAuthorization": true
39  },
40  "paymentMethod": {
41    "paymentMethodType": "CARD",
42    "paymentMethodMetaData":{
43        "paymentMethodRegion":"BR"
44    }
45  },
46  "paymentNotifyUrl": "https://www.google.com.sg",
47  "paymentRedirectUrl": "https://www.baidu.com",
48  "paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
49  "productCode": "CASHIER_PAYMENT",
50  "settlementStrategy": {
51    "settlementCurrency": "USD"
52  },
53  "enableInstallmentCollection":"true"
54}
支付会话创建请求的响应示例：
1{
2  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
3  "paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
4  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
5  "result": {
6    "resultCode": "SUCCESS",
7    "resultMessage": "success.",
8    "resultStatus": "S"
9  }
10}
4

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

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

SDK 提供的事件码如下：

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

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

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

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

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

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

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

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

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

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

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

集成代码关键步骤示例

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

1import { AMSCheckout } from "@alipay/ams-checkout";
2// 步骤一：实例化sdk
3const checkoutApp = new AMSCheckout({
4  mode: "component",
5  locale: "en_US",
6  environment: "sandbox",
7  networkMode: "session",
8  onLog: () => {},
9  onEventCallback: () => {},
10});
11// 处理卡支付按钮事件
12document
13  .querySelector("#你的表单id")
14  .addEventListener("submit", handleSubmit);
15
16async function handleSubmit() {
17  // 步骤二：服务端创建调用支付会话接口，获取paymentSessionData
18  async function getPaymentSessionData() {
19    const url = "填写服务端地址";
20    const config = {
21      // 填写请求配置
22    };
23    const response = await fetch(url, config);
24    // 获取响应中的paymentSessionData参数值
25    const { paymentSessionData } = await response.json();
26    return paymentSessionData;
27  }
28  const paymentSessionData = await getPaymentSessionData();
29
30  // 步骤三：创建渲染卡组件
31  // 最佳实践
32  const card = await checkoutApp.createComponent("card", {
33    paymentSessionData,
34  });
35}