Web/WAP
此章节为您提供 Web/Wap 端 SDK 嵌入式卡支付体验的集成指南,帮助您快速开始电脑浏览器及手机浏览器内支付相关页面的渲染。
在您开始集成前,请阅读 集成指南 及 API 概述 文档,了解服务端 API 的集成步骤及 API 的调用注意事项,并确保已完成以下预配置及环境准备工作:
- 安装 npm 包管理器。
- 处理兼容性问题:对于 IE 系列浏览器或其他低版本浏览器,需要提供相应的 Polyfill 支持,在项目构建时,建议使用 babel-preset-env 来解决浏览器兼容问题。
- 请使用建议的浏览器版本:
- 手机浏览器:
- 确保 iOS 11 及以上版本
- 确保 Android 6.0 及以上
- 电脑浏览器:推荐使用的浏览器版本如下 :
请根据以下步骤完成集成:
集成 SDK 资源包
请查阅 Web/WAP 端集成 SDK 资源包文档。
通过 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
。
- enabled: 选传,Boolean 类型。默认值为
onLog
: 选传,输出 SDK 运行期间触发的日志、接口异常等错误信息的回调函数。onEventCallback
: 选传,SDK 运行期间支付发生特定事件触发回调并返回具体事件码,例如支付结果、表单提交异常等。更多详情请查阅 参考信息 文档。onError
:选传,在 SDK 运行期间发生错误时被触发(如初始化异常、网络超时等问题)。详情请查阅 参考信息 错误码。
- locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器多语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下多语言信息的值,如果传入的值不是以下几种,将提供英语页面:
- 实例化
AMSCashierPayment
。
注意:使用 environment 设置环境参数时需要与步骤 3 发起 支付会话创建 请求的环境保持一致。
向 Alipay 服务器发起 支付会话创建 请求。
对于买家未绑卡支付与已绑卡后的令牌支付模式,请您按如下方式分别操作:
未绑卡模式:
在买家未绑定银行卡的前提下,你的客户端需要自行监听买家卡支付方式选择事件。当监听到买家选择卡支付方式后,您服务端需向 POP 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后,将响应中的 paymentSessionData 参数值用于步骤 4 。
卡令牌模式:
买家在支付方式选择已绑卡支付方式后,您的客户端进行支付按钮的点击事件监听。当监听到支付按钮被用户点击后,商户服务端需向 POP 服务器发起 支付会话创建 请求。卡令牌模式下您需要通过 paymentMethod.paymentMethodId 字段传入买家绑卡后 POP 返回给您的卡令牌,获取卡令牌方式如下:
- 独立绑卡:通过 POP 向您发送的资产保管结果通知中的 card.cardToken 字段获取卡令牌。
- 非独立绑卡:通过 POP 向您发送的支付结果通知或主动查询支付结果的响应中的 paymentResultInfo.cardToken 字段获取卡令牌。
收到支付会话创建请求的响应后,将响应中的 paymentSessionData 参数值用于步骤 4 。
使用实例对象中的 mountComponent
函数创建支付组件:
- 使用 sessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
- 调用实例对象中的
mountComponent()
函数,返回值为Promise
。支付区块 DOM 节点即可根据环境参数渲染出支付要素收集视图并插入当前页面中。- appearance:选传,Object 类型,用于自定义外观主题配置,包含以下参数:
- showLoading:选传,Boolean 类型。默认值为
true
,代表启用组件初始化的运行 loading 动画。如您不使用默认 loading 动画,需指定此值为false
。 - showSubmitButton:选传,Boolean 类型。默认值为
false
,表示不启用由组件渲染支付按钮。若设定该值为false
,则需要调用实例对象中submit()
函数触发提交支付流程。
- showLoading:选传,Boolean 类型。默认值为
- notRedirectAfterComplete:选传,Boolean 类型。默认值为
false
,表示支付完成后跳回您的页面,当值为空时同理。值为true
表示支付完成后不跳转,您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考,交易状态的更新请以服务端 支付结果通知 或 支付查询 接口返回结果为准。 - merchantAppointParam:选传,Object类型,用于自定义功能的设置,包含以下参数:
- storedCard:选传,Object 类型,用于在已存卡情况下设置自定义功能,包含以下参数:
- needCVV:选传,Boolean 类型,默认值为
false
,表示在支付过程中无需用户输入CVV校验,当值为空时同理。若设定该值为true
,则表示在支付过程中需要用户输入CVV校验。
- needCVV:选传,Boolean 类型,默认值为
- storedCard:选传,Object 类型,用于在已存卡情况下设置自定义功能,包含以下参数:
- appearance:选传,Object 类型,用于自定义外观主题配置,包含以下参数:
- 调用实例对象中的
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)。州、国家或省名称。
- billingAddress:选传,Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数:
-
调用实例对象中的
unmount()
函数进行 SDK 组件的资源回收,请在以下三种场景中调用:- 用户切换视图退出支付页面,需要回收 支付会话创建 中的组件资源。
- 用户发起多笔支付,需要回收上一次 支付会话创建 中的组件资源。
- 用户完成支付并配置了 notRedirectAfterComplete 为
true
,可获取明确支付结果事件码时,需要回收组件资源。
参考信息将为您提供回调函数事件码以及集成关键步骤代码示例,详情请查阅 参考信息 文档。