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

通过 AMSCahsierPayment 构造函数创建 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, message})=>{}
12});
3

向 APO 服务器发起 createPaymentSession 请求。

商户服务端

对于买家未绑卡支付与已绑卡后的令牌支付模式，请您按如下方式分别操作：

未绑卡模式：

在买家未绑定银行卡的前提下，你的客户端需要自行监听买家卡支付方式选择事件。当监听到买家选择卡支付方式后，您服务端需向 APO 服务器发起 createPaymentSession请求。收到支付会话创建请求的响应后，将响应中的 paymentSessionData 参数值用于步骤 4 。

 

卡令牌模式：

买家在支付方式选择已绑卡支付方式后，您的客户端进行支付按钮的点击事件监听。当监听到支付按钮被用户点击后，商户服务端需向 APO 服务器发起 createPaymentSession 请求。卡令牌模式下您需要通过 paymentMethod.paymentMethodId 字段传入买家绑卡后 APO 返回给您的卡令牌，获取卡令牌方式如下：

  • 独立绑卡：通过 APO 向您发送的资产保管结果通知中的 card.cardToken 字段获取卡令牌。
  • 非独立绑卡：通过 APO 向您发送的支付结果通知或主动查询支付结果的响应中的 paymentResultInfo.cardToken 字段获取卡令牌。

收到支付会话创建请求的响应后，将响应中的 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

使用实例对象中的 mountComponent 函数创建支付组件：

商户客户端
  • 使用 sessionData 参数创建配置对象: 将 createPaymentSession 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
  • 调用实例对象中的 mountComponent() 函数，返回值为 Promise。支付区块 DOM 节点即可根据环境参数渲染出支付要素收集视图并插入当前页面中。
    • appearance：选传，Object 类型，用于自定义外观主题配置，包含以下参数：
      • showSubmitButton：选传，Boolean 类型。默认值为 false，表示不启用由组件渲染支付按钮。若设定该值为 false，则需要调用实例对象中 submit() 函数触发提交支付流程。
    • notRedirectAfterComplete：选传，Boolean 类型。默认值为 false，表示支付完成后跳回您的页面，当值为空时同理。值为 true 表示支付完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 notifyPayment 或 inquiryPayment 接口返回结果为准。
    • merchantAppointParam：选传，Object 类型，用于自定义功能的设置，包含以下参数：
      • storedCard：选传，Object 类型，用于在已存卡情况下设置自定义功能，包含以下参数：
        • needCVV：选传，Boolean 类型，默认值为 false，表示在支付过程中无需用户输入 CVV 校验，当值为空时同理。若设定该值为 true ，则表示在支付过程中需要用户输入 CVV 校验。
  • 调用实例对象中的 submit() 函数，可触发支付提交流程，返回值为 Promise，返回特定事件码。这些事件码也会通过 onError 或 onEventCallback 等事件返回。
  • 如果您需要传入提前收集好的 billing address 信息用于 AVS 验证，您可配置如下参数通过 submit 函数传入。
    • billingAddress：选传，Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数：
      • region：必传，String (2)。遵循 ISO 3166 标准的二位国家码。
      • zipCode：选传，String (32)。邮政编码。
      • address2：选传，String (256)。地址行 2，例如公寓、套房、单元和建筑物信息。
      • address1：选传，String (256)。地址行 1，例如街道地址、邮政信箱和公司名称。
      • city：选传，String (32)。城市、地区、郊区、城镇或村庄名称。
      • state：选传，String (8)。州、国家或省名称。

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

    • 用户切换视图退出支付页面，需要回收 createPaymentSession 中的组件资源。
    • 用户发起多笔支付，需要回收上一次 createPaymentSession 中的组件资源。
    • 用户完成支付并配置了 notRedirectAfterComplete 为  true，可获取明确支付结果事件码时，需要回收组件资源。
调用 mountComponent()
1async function create(sessionData) {
2  await checkoutApp.mountComponent({ 
3    sessionData:sessionData,
4    appearance:{
5      showSubmitButton: false, // 默认为false，表示不启用组件渲染支付按钮
6    }, 
7   notRedirectAfterComplete: false,
8   merchantAppointParam: {
9      storedCard: {
10        needCVV: false, // 默认为false，表示不需要用户输入CVV校验
11      },
12   },
13  },'#ContainerNodeId');
14}
15// 用户输入地址信息并存储在billingAddress对象中，用于后续提交
16const billingAddress = {
17  region: '',
18  address1: '',
19  address2: '',
20  city: '',
21  state: '',
22  zipCode: ''
23}
24
25// 当用户完成表单填写，点击提交按钮时执行
26checkoutApp.submit({billingAddress}).then(({code, message})=>{})
27
28// 按情况执行销毁函数
29// checkoutApp.unmount();
参考信息

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