Web/WAP

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

 

集成准备

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

  • 安装 npm 包管理器。
  • 处理兼容性问题：对于 IE 系列浏览器或其他低版本浏览器，需要提供相应的 Polyfill 支持，在项目构建时，建议使用 babel-preset-env 来解决浏览器兼容问题。
  • 请使用建议的浏览器版本：
    • 手机浏览器：
      • 确保 iOS 11 及以上版本
      • 确保 Android 6.0 及以上
    • 电脑浏览器：推荐使用的浏览器版本如下 : 

imageEdge

最近两个版本

imageFirefox

最近两个版本

imageChrome

最近两个版本

imageSafari

最近两个版本

imageOpera

最近两个版本

imageElectron

最近两个版本

关键集成步骤

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

1

集成 SDK 资源包

商户客户端

请查阅 Web/WAP 端集成 SDK 资源包文档。

 

2

通过 AMSCashierPayment 构造函数创建 SDK 实例：

商户客户端
  • 创建 config 对象：必传，Object 类型。包含所有配置参数：
    • locale: 选传，String 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器多语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下多语言信息的值，如果传入的值不是以下几种，将提供英语页面：
      • en_US：英语
      • es_ES：西班牙语
      • fr_FR：法语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • zh_CN：简体中文
    • environment: 必传，String 类型。用于传入环境参数，支持的值包括：
      • sandbox：沙箱环境
      • prod：生产环境
    • analytics：选传，Object 类型，用于配置分析数据服务，包含以下参数：
      • enabled: 选传，Boolean 类型。默认值为 true ，代表允许 SDK 上传分析运行数据以提供更好的服务。如您不允许上传分析运行数据，需指定此值为 false 。
    • onLog: 选传，输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。
    • onEventCallback: 选传，SDK 运行期间支付发生特定事件触发回调并返回具体事件码，例如支付结果、表单提交异常等。更多详情请查阅参考信息文档。
    • onError：选传，在 SDK 运行期间发生错误时被触发（如初始化异常、网络超时等问题）。详情请查阅 参考信息 错误码。
  • 实例化 AMSCashierPayment。

注意：使用 environment 设置环境参数时需要与步骤 3 发起 createPaymentSession 请求的环境保持一致。

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

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

商户服务端

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

对于已绑卡的卡令牌支付模式下您需要通过 paymentMethod.paymentMethodId 字段传入买家绑卡后 APO 返回给您的卡令牌，获取卡令牌方式如下：

  • 独立绑卡：通过 APO 向您发送的资产绑定结果通知中的 card.cardToken 字段获取卡令牌。
  • 非独立绑卡：通过 APO 向您发送的支付结果通知或主动查询支付结果的响应中的 paymentResultInfo.cardToken 字段获取卡令牌。
以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：
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 函数创建支付组件:

商户客户端
  • 使用 sessionData 参数创建配置对象: 将 createPaymentSession 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
  • 调用实例对象中的 createComponent() 函数，返回值为 Promise。支付区块 DOM 节点即可根据参数在当前页面渲染出浮层视图。
    • notRedirectAfterComplete：选传，Boolean 类型。默认值为 false，表示支付完成后跳回您的页面，当值为为空时同理。值为 true 表示支付完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 notifyPayment 或 inquiryPayment 接口返回结果为准。
    • merchantAppointParam：选传，Object类型，用于自定义功能设置，包含以下参数：
      • storedCard：选传，Object 类型，用于已存卡情况下的自定义功能设置，包含以下参数：
        • needCVV：选传，Boolean 类型，默认值为 false，表示在支付过程中无需用户输入CVV校验，当值为空时同理。若设定该值为 true，则表示在支付过程中需要用户输入CVV校验。

  • 调用实例对象中的 unmount() 函数进行 SDK 组件的资源回收，请在以下三种场景中调用：

    • 用户切换视图退出支付页面，需要回收 createPaymentSession 中的组件资源。
    • 用户发起多笔支付，需要回收上一次 createPaymentSession 中的组件资源。
    • 用户完成支付并配置了 notRedirectAfterComplete 为 true，可获取明确支付结果事件码时，需要回收组件资源。
调用 createComponent()
1async function create(sessionData) {
2  await checkoutApp.createComponent({ 
3    sessionData: paymentSessionData, 
4    notRedirectAfterComplete: true,
5    merchantAppointParam: {
6        storedCard: {
7          needCVV: true, // 默认为false，表示不需要用户输入CVV校验
8        },
9    },
10  });
11}
12//按情况执行销毁函数
13checkoutApp.unmount();
参考信息

参考信息将为您提供回调函数事件码以及集成关键步骤代码示例，详情请查阅 SDK 参考信息文档。