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 提供的多语言信息，您可以根据支付方式所在地区选择需要传入的值，如果传入的语言不在以下范围内，SDK 将提供英语页面：
      • en_US：英语
      • pt_BR：葡萄牙语
      • ko_KR：韩语
      • es_ES：西班牙语
      • fr_FR：法语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • zh_CN：中文简体
      • zh_HK：中文繁体
      • ms_MY：马来语
      • vi_VN：越南语
      • in_ID：印尼语
      • th_TH：泰语
    • environment：必传，String 类型。用于传入环境参数，支持的值包括：
      • sandbox：沙箱环境
      • prod：生产环境
    • analytics：选传，Object 类型，用于配置分析数据服务，包含以下参数：
      • enabled：选传，Boolean 类型。默认值为 true ，代表允许 SDK 上传分析运行数据以提供更好的服务。如您不允许上传分析运行数据，需指定此值为 false 。
    • onLog：选传，输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。
    • onError：选传，在 SDK 运行期间发生错误时被触发（如初始化异常、网络超时等问题）。详情请参考 SDK 错误码。
    • onEventCallback：必传，SDK 运行期间支付发生特定事件触发回调并返回具体事件码，例如支付结果、支付取消等。更多详情请查阅参考信息文档。
  • 实例化 AMSCashierPayment。

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

获取浏览器语言
1let language = navigator.language || navigator.userLanguage;
2language = language.replace("-", "_"); // 将 "-" 替换成 "_"
npm 引包方式和 CDN 引包方式展示
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, mesaage, stack})=>{}
12});
3

发起 支付会话创建 请求

商户服务端

商户客户端自行监听支付按钮的点击事件。当买家选择支付方式并点击支付按钮后，商户服务端向 APO 服务器发起 createPaymentSession 请求。一旦接收到 createPaymentSession 请求的响应，将响应中的 paymentSessionData 值用于步骤 4。

支付会话创建请求示例
1{
2  "settlementStrategy": {
3    "settlementCurrency": "USD"
4  },
5  "productCode": "CASHIER_PAYMENT",
6  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_online&paymentMethodType=GRABPAY_SG",
7  "paymentRequestId": "yourPaymentRequestId2",
8  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=amsdmpay_yanhong_yan_20240201_114714_703",
9  "paymentMethod": {
10    "paymentMethodType": "GCASH"
11  },
12  "paymentAmount": {
13    "currency": "PHP",
14    "value": "30000"
15  },
16  "order": {
17    "orderAmount": {
18      "currency": "SGD",
19      "value": "30000"
20    },
21    "orderDescription": "yourDescription",
22    "referenceOrderId": "yourOrderId"
23  },
24  "env": {
25    "clientIp": "1.1.1.1"
26  }
27}
4

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

商户客户端
  • 使用 sessionData 参数创建配置对象：将 createPaymentSession 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
  • 调用实例对象中的 createComponent() 函数，返回值为 Promise。支付区块 DOM 节点即可根据参数在当前页面渲染出浮层视图。

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

调用 createComponent()
1async function create(sessionData) {
2  await checkoutApp.createComponent({ 
3    sessionData: sessionData, 
4  });
5}
6//销毁组件
7checkoutApp.unmount();
5

支付过程事件与支付结果展示

商户客户端

支付过程事件

在 SDK 运行期间通过 onEventCallback 回调函数返回支付过程状态码，以下几组状态码需要您特别关注并做进一步处理：

  • 当用户在未提交订单状态下退出支付页面时，您会收到以下事件码：
    • SDK_PAYMENT_CANCEL：当收到此事件码时，建议您引导用户再次支付。

 

支付结果展示

  • 跳端支付：在支付流程结束时，跳端支付方式会根据支付结果将用户重定向到您传入的回跳URL上，进而引导用户进行下一步操作。
  • 非跳端支付：在支付流程结束时，非跳端支付方式将为您返回与支付结果相关的事件码，您可以根据不同的支付结果做进一步处理：
    • SDK_PAYMENT_SUCCESSFUL：支付成功。建议您重定向到支付结果页。
    • SDK_PAYMENT_FAIL：支付失败。建议您检查 onEventCallback 函数 result 数据中 paymentResultCode 的值，并在文末参考信息“支付失败或异常说明”表格中查阅进一步的行动建议，根据行动建议引导用户重新支付。
    • SDK_PAYMENT_ERROR：支付状态异常。建议您检查 onEventCallback 函数 result 数据中 paymentResultCode 的值，并在文末参考信息“支付失败或异常说明”表格中查阅进一步的行动建议。
    • SDK_PAYMENT_PROCESSING：支付处理中。建议您检查 onEventCallback 函数 result 数据中 paymentResultCode 的值，并在文末参考信息“支付失败或异常说明”表格中查阅进一步的行动建议。

注意：此处的支付结果仅做前端展示，最终订单状态请以服务端为准。

onEventCallback 函数事件码处理示例
1function onEventCallback({ code, result }) {
2  switch (code) {
3    case code:
4      'SDK_PAYMENT_SUCCESSFUL';
5      // 支付成功。建议您重定向到支付结果页。
6      break;
7    case code:
8      'SDK_PAYMENT_PROCESSING';
9      console.log('可检查支付结果数据', result);
10      // 支付处理中。建议您通过服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果未完成，可以引导用户重新支付。
11      break;
12    case code:
13      'SDK_PAYMENT_FAIL';
14      console.log('可检查支付结果数据', result);
15      // 支付失败。建议您查阅文末参考信息 paymentResultCode 中的处理建议，并引导用户重新支付。
16      break;
17    case code:
18      'SDK_PAYMENT_CANCEL';
19      // 用户在未提交订单状态下退出支付页面。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
20      break;
21    case code:
22      'SDK_PAYMENT_ERROR';
23      console.log('可检查支付结果数据', result);
24      // 支付状态异常。建议您通过服务端查询支付状态或等待支付结果通知，或引导用户重新支付。
25      break;
26    default:
27      break;
28  }
29}
onEventCallback 函数 result 数据示例
1{
2  "code": "SDK_PAYMENT_SUCCESSFUL",  // 前端事件码
3  "result":{
4    "result": {
5      "resultCode": "SUCCESS",
6        "resultStatus": "S",
7        "resultMessage": "Success"
8    },
9    "paymentResultCode": "SUCCESS", //在resultStatus为S时返回
10    "paymentResultMessage": "success",  //在resultStatus为S时返回
11    "paymentStatus": "SUCCESS"
12  }  
13}
参考信息

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