Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Web/Wap

此章节为您提供 EasySafePay 的集成指南,帮助您在买家进行支付时快速开始电脑浏览器以及手机浏览器内支付相关页面的渲染。最优体验与跳端体验集成流程一致。

 

集成准备

在您开始集成前,确保已完成以下环境准备工作:

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

       

      Web/WapEdge

      不限版本

      Web/WapFirefox

       Last 2 versions

      Web/WapChrome

       Last 2 versions

      Web/WapSafari

       Last 2 versions

      Web/WapOpera

       Last 2 versions

      Web/WapElectron

       Last 2 versions

集成步骤

首次支付和再次支付场景的集成步骤如下:

1

集成 SDK 资源包

商户客户端

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

 

2

展示支付方式

商户客户端

您可以使用该 工具 获取支付方式并自定义其 logo 样式,然后将支付方式的 logo 等信息展示在您的收银台页面。

首次支付呈现支付方式时,建议您将支付方式名称及其 logo 一并展示,供买家点击。再次支付呈现支付方式时,建议您将支付方式名称及其 logo 以及脱敏的买家账号一并展示,供买家点击。

Web/Wap
3

通过 AMSEasyPay构造函数创建 SDK 实例:

商户客户端
  1. 创建 config 对象:必传,Object 类型。包含所有配置参数:
    • locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下 8 种多语言,如果传入的值不是以下 8 种,将提供英语页面:
      • en_US:英语
      • in_ID:印尼语
      • th_TH:泰语
      • ms_MY:马来西亚语
      • tl_PH:菲律宾语
      • ko_KR:韩语
      • vi_VN:越南语
      • zh_HK:繁体中文(中国香港)​
    • environment: 必传,String 类型。用于传入环境参数,支持的值包括:
      • sandbox:沙箱环境
      • prod:生产环境
    • analytics:选传,Object 类型,用于配置分析数据服务,包含以下参数:
      • enabled: 选传,Boolean 类型。默认值为 true ,代表允许 SDK 上传分析运行数据以提供更好的服务。如您不允许上传分析运行数据,需指定此值为 false 。
    • onLog: 选传,输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。
    • onEventCallback: 选传,SDK 运行期间支付发生特定事件触发回调并返回具体事件码。
  2. 实例化 AMSEasyPay

 

获取浏览器语言的代码示例
JavaScript
Editor
以下示例针对 npm 引包方式展示创建 SDK 实例的代码示例:
JavaScript
Editor
以下示例针对 CDN 引包方式展示创建 SDK 实例的代码示例:
JavaScript
Editor
4

发起支付会话创建请求

商户服务端

商户客户端自行监听支付按钮的点击事件。当买家选择支付方式并点击支付按钮后,商户服务端向 Alipay 服务器发起 支付会话创建 请求。一旦接收到 支付会话创建 请求的响应,将响应中的 paymentSessionData 值用于步骤五。对于首次支付和再次支付,您需要在请求中传入不同参数:

  • 首次支付
    • paymentRedirectUrl:商家回跳地址。建议您传入H5类型的链接。
    • authState:商家分配的发起授权的唯一标识,用于获取后续免密支付的令牌。该参数仅首次支付必传,再次支付您无需传入该参数。
    • paymentNotifyUrl:支付结果通知地址。该地址必须为 HTTPS。
    • paymentSessionExpiryTime:支付会话的超时时间。默认是 1 小时,可设置为 1 小时内的超时时间,值的格式遵循 ISO 8601 标准。例如,2019-11-27T12:01:01+08:00。
    • userLoginId:买家钱包侧登录账号,可以是买家的邮箱地址或电话号码。
    • order.buyer: referenceBuyerId/buyerPhoneNo/buyerEmail:传入用户信息用于风险决策。传入 referenceBuyerId、buyerPhoneNo、buyerEmail 其中一个参数即可。
  • 再次支付
    • paymentMethod.paymentMethodId:传入首次签约支付接受的 授权通知 accessToken 的值。
    • paymentRedirectUrl:商家回跳地址。建议您传入H5类型的链接。
    • paymentNotifyUrl:支付结果通知地址。该地址必须为 HTTPS。
    • paymentSessionExpiryTime:支付会话的超时时间。默认是 1 小时,可设置为 1 小时内的超时时间,值的格式遵循 ISO 8601 标准。例如,2019-11-27T12:01:01+08:00。
    • order.buyer. referenceBuyerId/buyerPhoneNo/buyerEmail:传入用户信息用于风险决策。传入 referenceBuyerId、buyerPhoneNo、buyerEmail 其中一个参数即可。
首次支付
JSON
Editor
再次支付
JSON
Editor
5

渲染支付页面

商户客户端

使用实例对象中的 createComponent 函数:

  • 使用 sessionData 参数创建配置对象: 将步骤 4 获取的 paymentSessionData 字段的完整数据传入 createComponentsessionData 参数。
  • 调用实例对象中的 createComponent()函数,返回值为 Promise,内容为使用该函数所得的组件实例对象。支付区块 DOM 节点即可根据环境参数渲染出支付方式视图并插入当前页面中。您可以配置以下参数:
    • appearance:选传,Object 类型,用于自定义外观主题配置,包含以下参数:
      • showLoading: 选传,Boolean 类型。默认值为 true ,代表展示默认loading 动画。如您不使用默认 loading 动画,需指定此值为 false 。​​​

 

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

  • 用户退出支付页面时,需要回收 支付会话创建 中的组件资源。
  • 用户发起多笔支付时,需要回收上一次 支付会话创建 中的组件资源。
调用 createComponent()
JavaScript
Editor
6

获取授权或支付结果

商户服务端

无论是跳端体验还是标准体验,首次支付场景您可以获取到授权和支付结果,再次支付场景您可以获取到支付结果:

  • 获取授权结果
    当授权成功后,支付宝会通过 签约结果通知 发送异步通知到您在开发者中心配置的接口地址,若您收到支付宝的异步通知,需要您在返回中按照 示例代码 格式返回响应。您需要更新您系统内用户的签约状态,同时建议在您的签约管理页通过通知里的钱包账号信息展示对应的钱包脱敏账号。
  • 获取支付结果
    当支付到达成功或失败终态后,支付宝会通过 支付结果通知 发送到您在支付会话请求里传的 paymentNotifyUrl。若您收到支付宝的异步通知,需要您在返回中按照 示例代码 格式返回响应。

注意】在买家放弃支付的场景下,您调用 查询支付结果 接口和 取消 接口,均可能会返回订单不存在,且您也不会收到支付失败的异步通知。 建议您采取如下解决方案:

  • 在您主动关闭订单的场景下,建议方案如下:
    • 商家侧关闭订单后收到 Alipay 通知,订单状态为成功支付,此时无需额外操作。
    • 商家侧关闭订单后收到 Alipay 通知,订单状态未更新,则调用 取消 接口取消对应 Alipay 订单。
  • 在重复支付的场景(一笔商家订单对应多笔支付宝订单)下,如您收到多笔 Alipay 订单支付成功通知,只保留其中一笔 Alipay 订单成功结果,其余 Alipay 订单都通过 取消 接口完成取消订单。
事件码

SDK 提供的状态码如下:

  • SDK_START_OF_LOADING:创建组件时,loading 动画开始显示。

  • SDK_END_OF_LOADING:创建组件时,loading 动画结束显示。

 

SDK 提供的错误码如下: 

  • SDK_INTERNAL_ERROR:SDK 内部错误,请联系技术支持。

  • SDK_CREATEPAYMENT_PARAMETER_ERRORAMSEasyPay函数传入参数异常,请检查参数是否正确传递并重试请求。

  • SDK_INIT_PARAMETER_ERRORcreateComponent 函数传入参数异常,请检查参数是否正确传递并重试请求。

  • SDK_CREATECOMPONENT_ERRORcreateComponent 函数调用异常,请联系技术支持。

  • SDK_CALL_URL_ERROR:唤起支付方式客户端异常,请联系技术支持。