Web/WAP
此章节为您提供银行 SDK 的集成指南,帮助您在买家进行支付时快速开始电脑浏览器以及手机浏览器内支付相关页面的渲染。
在您开始集成前,确保已完成以下环境准备工作:
- 已安装 npm。
- 兼容性问题处理:对于 IE 系列浏览器或其他低版本浏览器,需要提供相应的 Polyfill 支持,在项目构建时,建议使用 babel-preset-env 来解决浏览器兼容问题。
- 请使用建议的系统版本:
- 手机浏览器:
- 确保 iOS 11 及以上版本
- 确保 Android 5.0 及以上
- 电脑浏览器:推荐使用的浏览器版本如下 :
- 手机浏览器:
请根据以下步骤完成集成:
集成 SDK 资源包
请查阅 集成 SDK 资源包 文档。
展示支付方式
在您通过联系支付宝技术支持团队获取到可用支付方式后,您可以按照以下维度呈现支付方式:
- 单一银行展示:将支付方式逐个平铺展示。
- 银行类型展示:根据银行类型聚合的维度分类展示支付方式,例如,银行 App、在线网银、银行转账。
- 银行国家展示:根据国家聚合的维度分类展示支付方式,例如,泰国银行、印尼银行。
三种维度的用户体验图请参考 User experience。
【注意】在银行类型展示模式下,Web 端不支持展示银行 App 类别的支付方式,仅 WAP 和 App 端支持展示。
通过 AMSCashierPayment
构造函数创建 SDK 实例:
- 创建 config 对象:必传,Object 类型。包含所有配置参数:
- locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下 3 种多语言,如果传入的值不是以下 3 种,将提供英语页面:
en_US
:英语in_ID
:印尼语th_TH
:泰语
- environment: 必传,String 类型。用于传入环境参数,支持的值包括:
SANDBOX
:沙箱环境-
PROD
:生产环境
- analytics:选传,Object 类型,用于配置分析数据服务,包含以下参数:
- enabled: 选传,Boolean 类型。默认值为
true
,代表允许 SDK 上传分析运行数据以提供更好的服务。如您不允许上传分析运行数据,需指定此值为false
。
- enabled: 选传,Boolean 类型。默认值为
-
onLog
: 选传,输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。 onClose
: 选传,买家点击关闭浮窗时触发回调函数。onEventCallback
: 选传,SDK 运行期间支付发生特定事件触发回调并返回具体事件码。
- locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下 3 种多语言,如果传入的值不是以下 3 种,将提供英语页面:
- 实例化
AMSCashierPayment
。
发起 支付会话创建 请求
商户客户端自行监听支付按钮的点击事件。当买家选择支付方式并点击支付按钮后,商户服务端向 Alipay 服务器发起 支付会话创建 请求。一旦接收到 支付会话创建 请求的响应,将响应中的 paymentSessionData 值用于步骤五。您需要在请求中传入以下参数:
-
paymentRequestId:商户侧支付宝的交易号。
-
productCode:产品码,传入固定值
CASHIER_PAYMENT
。 -
paymentNotifyUrl:支付结果通知地址。
- paymentRedirectUrl:支付完成后回跳的商家结果页地址
- paymentAmount:需要向买家收取的支付金额
- order.orderAmount: 商家侧的订单金额。若出现促销打折,orderAmount金额可能不等于 paymentAmount。
- order.orderDescription:订单描述
- order.referenceOrderId:商户侧自己的订单号。若商家侧一笔订单存在多次请求支付宝支付的情况下,referenceOrderId和paymentRequestId建议是一对多的关系。
- paymentMethod.paymentMethodType:指定为
BANK
。 - paymentMethod.paymentMethodMetaData:
- 若集成单一银行模式,则指定 bankName 为银行名称。
- 若集成银行类型聚合模式,则指定 paymentMethodCaregory 为支付方式类型。有效值为
BANK_TRANSFER
、MOBILE_BANKING_APP
和ONLINE_BANKING
。 - 若集成国家聚合模式,则指定 paymentMethodRegion 为国家。有效值为
TH
和ID
。
渲染支付页面
使用实例对象中的 createComponent()
函数:
- 使用 sessionData 参数创建配置对象: 将步骤 4 获取的 paymentSessionData 字段的完整数据传入 createComponent 的 sessionData 参数。
- 调用实例对象中的
createComponent()
函数,返回值为 Promise,内容为使用该函数所得的组件实例对象。支付区块 DOM 节点即可根据环境参数渲染出支付方式视图并插入当前页面中。您可以配置以下参数:- appearance:选传,Object 类型,用于自定义外观主题配置,包含以下参数:
- showLoading: 选传,Boolean 类型。默认值为
true
,代表展示默认loading 动画。如您不使用默认 loading 动画,需指定此值为false
。
- showLoading: 选传,Boolean 类型。默认值为
- appearance:选传,Object 类型,用于自定义外观主题配置,包含以下参数:
调用实例对象中的 unmount()
函数进行 SDK 组件的资源回收,请在以下两种场景中调用:
- 用户退出支付页面时,需要回收 支付会话创建 中的组件资源。
- 用户发起多笔支付时,需要回收上一次 支付会话创建 中的组件资源。
SDK 提供的状态码如下:
-
SDK_START_OF_LOADING
:创建组件时,loading 动画开始显示。 -
SDK_END_OF_LOADING
:创建组件时,loading 动画结束显示。
SDK 提供的错误码如下:
-
SDK_INTERNAL_ERROR
:SDK 内部错误,请联系技术支持。 -
SDK_CREATEPAYMENT_PARAMETER_ERROR
:AMSCashierPayment
函数传入参数异常,请检查参数是否正确传递并重试请求。 -
SDK_INIT_PARAMETER_ERROR
:createComponent
函数传入参数异常,请检查参数是否正确传递并重试请求。 -
SDK_CREATECOMPONENT_ERROR
:createComponent
函数调用异常,请联系技术支持。 -
SDK_CALL_URL_ERROR
:唤起支付方式客户端异常,请联系技术支持。