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

Android

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

集成准备

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

  • 已安装最新版本的 Android Studio。
  • 目标运行环境须为 API 级别 19 及更高版本。
  • 使用 Gradle 4.1 及以上版本。
  • 配置物理机或模拟器,用于运行您的应用。
集成步骤

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

1

集成 SDK 资源包

商户客户端

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

 

 

2

展示支付方式

商户客户端

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

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

Android
3

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

商户客户端

创建 SDK 实例的过程包含以下步骤:

  1. 创建configuration对象:必传,Object类型。包含所有配置参数:
    • ​setLocale: 选传,String类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下 8 种多语言,如果传入的值不是以下 8 种,将提供英语页面:
      • locale("en", "US"):英语
      • locale("in", "ID"):印尼语
      • locale("th", "TH"):泰语
      • locale("ms", "MY"):马来西亚语
      • locale("tl", "PH"):菲律宾语
      • locale("ko", "KR"):韩语
      • locale("vi", "VN"):越南语
      • locale("zh", "HK"):繁体中文(中国香港)
    • setOption: 选传,用于设置是否采用默认loading样式以及是否使用沙箱环境,支持的值包括:
      • "sandbox", "true":沙箱环境
      • "sandbox", "false":生产环境
      • "showLoading", "true":使用默认 loading 样式
      • "showLoading", "false":不使用默认 loading 样式
      • "windowGravity","LANDSCAPE_CENTER":横屏模式下设置窗口居中
      • "windowGravity","LANDSCAPE_RIGHT":横屏模式下设置窗口居右
  2. 创建 onCheckoutListener 接口的实例,用于后续流程中对应事件发生时的处理,包含以下方法:
    • onEventCallback: 必传。收银台支付事件回调函数,返回事件码(eventCode)和事件具体信息(eventResult)。
  3. 将 onCheckoutListener 接口的实例设置到 configuration 实例中,用于执行事件回调。
  4. 实例化 AMSEasyPay

注意】为了更好的用户体验,在发起支付会话请求前,商户可提前创建组件实例来提升组件性能。

创建组件实例:
Java
Editor
4

发起 支付会话创建 请求

商户服务端

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

对于首次支付和再次支付,您需要在请求中传入不同参数:

  • 首次支付
    • paymentRedirectUrl:商家回跳地址。建议您传入 schema 类型的链接。
    • 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:商家回跳地址。建议您传入 schema 类型的链接。
    • 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

渲染支付页面

商户客户端

AMSEasyPay 组件不能重复使用,每次创建支付会话请求时,需要重新创建一个 AMSEasyPay 组件。

调用实例对象中的 createComponent() 并传入以下参数:

  • activity: 必传。Activity 类型的一个对象,用于包含当前页面的上下文参数信息。
  • sessionData:必传。String 类型。将步骤 4 获取的的 paymentSessionData 字段的完整数据传入 createComponent 的 sessionData 参数。

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

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

获取授权或支付结果

商户服务端

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

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

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

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

SDK 提供的状态码如下:

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

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

  • SDK_PAYMENT_CANCEL:用户在账号确认页和大额确认页主动取消支付流程。

 

SDK 提供的错误码如下: 

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

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

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

  • SDK_INTEGRATION_ERROR:相关依赖包缺失,请检查依赖代码是否正确添加并重试。

集成代码关键步骤示例

以下代码示例展示了集成过程中的关键步骤。

Java
Editor