Web/WAP

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

集成准备

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

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

Edge

Firefox

Last 2 versions

Chrome

Last 2 versions

Safari

Last 2 versions

Opera

Last 2 versions

Electron

Last 2 versions

关键集成步骤

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

集成 SDK 资源包

商户客户端

请查阅集成 SDK 资源包文档。

通过 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 运行期间支付发生特定事件触发回调并返回具体事件码，例如支付结果、表单提交异常等。更多详情请查阅参考信息文档。
实例化 AMSCashierPayment 。

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

获取浏览器语言的代码示例

let language = navigator.language || navigator.userLanguage;
language = language.replace("-", "_"); // 将 "-" 替换成 "_"

以下示例分别针对 npm 引包方式和 CDN 引包方式展示创建 SDK 实例的代码示例：

import { AMSCashierPayment } from "@alipay/ams-checkout"; // 包管理

const checkoutApp = new AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  analytics: {
    enabled: true,
  },
  onLog: ({ code, message }) => {},
  onEventCallback: ({ code, result }) => {},
});

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

商户服务端

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

以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：

{
  "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"
}

支付会话创建请求的响应示例：

{
  "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"
  }
}

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

商户客户端

使用 sessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
调用实例对象中的 createComponent() 函数，返回值为 Promise, 支付区块 DOM 节点即可根据参数在当前页面渲染出浮层视图。
- notRedirectAfterComplete：选传，Boolean 类型。默认值为 false，表示支付完成后跳回您的页面，当值为空时同理。值为 true 表示支付完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 支付结果通知 或 支付查询 接口返回结果为准。
调用实例对象中的 unmount() 函数进行 SDK 组件的资源回收，请在以下三种场景中调用：
- 用户切换视图退出支付页面，需要回收 支付会话创建 中的组件资源。
- 用户发起多笔支付，需要回收上一次 支付会话创建 中的组件资源。
- 用户完成支付并配置了 notRedirectAfterComplete 为 true，可获取明确支付结果事件码时，需要回收组件资源。

调用 createComponent()

async function create(sessionData) {
  await checkoutApp.createComponent({
    sessionData: sessionData,
    notRedirectAfterComplete: false,
  });
}
// 按情况执行销毁函数
// checkoutApp.unmount();

参考信息

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