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

iOS

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

集成准备

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

  • 已安装 Xcode 12 或更高版本。
  • 确保 iOS 系统为 iOS 11 及以上版本。
  • SDK 安全扩展包暂不支持模拟器编译,请在真机上集成 SDK 并完成编译。
集成步骤

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

1

集成 SDK 资源包

商户客户端

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

 

 

2

展示支付方式

商户客户端

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

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

iOS
3

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

商户客户端
  1. 初始化收银台实例,包含以下参数:
    • configuration:必传,AMSEasyPayConfiguration 类型的一个对象,包含所有配置参数。
  2. 创建 AMSEasyPayConfiguration 类,包含以下参数:
    • ​​locale: 选传,NSString 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种多语言,如果传入的值不是以下几种,将提供英语页面:
      • en_US:英语
      • in_ID:印尼语
      • th_TH:泰语
      • ms_MY:马来西亚语
      • tl_PH:菲律宾语
      • ko_KR:韩语
      • vi_VN:越南语
      • zh_HK:繁体中文(中国香港)
    • options: 选传,NSDictionary 类型,用于设置是否采用默认loading样式以及是否使用沙箱环境,支持的值包括:
      • "sandbox", "true":沙箱环境
      • "sandbox", "false":生产环境
      • "showLoading", "true":使用默认 loading 样式
      • "showLoading", "false":不使用默认 loading 样式
  3. 实现 AMSPaymentProtocol 的协议,用于后续流程中对应事件发生时的处理,包含以下方法:
    • onEventCallback:收银台支付事件回调函数,返回事件码(eventCode)和事件具体信息(eventResult)。
  4. 实现 AMSLoggerProtocol 的协议,用于管理日志输出,包含以下方法:
    • logWithName:默认输出日志的回调函数。
  5. 集成 Alipay CN(可选):配置 fromScheme,支付完成后回跳到商户 App 页面。
创建 SDK 实例的接口示例:
Objective-C
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

渲染支付页面

商户客户端

使用实例对象中的 createComponent:

  • 使用 sessionData 参数创建配置对象: 将步骤 4 获取的  paymentSessionData 字段的完整数据传入 createComponent 的 sessionData 参数。
  • 调用 createComponent() 函数初始化 SDK。

 

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

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

接收回调函数通知(接入 Alipay CN 时)

商户客户端

当您接入 Alipay CN 时,商户客户端可以接收来自回调函数的通知。收到回调函数通知后,在 AppDelegate -> openURL 方法中处理 Alipay CN 返回的结果数据。

Objective-C
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_ERRORcreatePaymentSession 接口请求参数异常,请检查参数是否正确传递并重试请求。

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

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