iOS

此章节为您提供 iOS 端浮层式绑卡体验 SDK 的集成指南，帮助您快速开始手机 App 内绑卡相关页面的渲染。

 

集成准备

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

  • 已安装 Xcode 12 或更高版本。
  • 确保 iOS 系统为 iOS 11 及以上版本。

 

关键集成步骤

请根据以下步骤完成集成：

1

集成 SDK 资源包。

商户客户端

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

 

 

2

通过 AMSVaulting 创建 SDK 实例：

商户客户端
  1. 初始化收银台实例，包含以下参数：
    • configuration：必传，AMSVaultingConfiguration 类型的一个对象，包含所有配置参数。
  2. 创建 AMSVaultingConfiguration 类，包含以下参数：
    • locale: 选传，NSString 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种语言，如果传入的值不是以下几种，将提供英语页面：
      • en_US：英语
      • pt_BR：葡萄牙语
      • ko_KR：韩语
      • es_ES：西班牙语
      • fr_FR：法语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • zh_CN：中文简体
      • zh_HK：中文繁体
    • options: 选传，NSDictionary 类型，用于设置是否使用沙箱环境，支持的值包括：​
      • "sandbox", "true"：沙箱环境
      • "sandbox", "false"：生产环境
      • "notRedirectAfterComplete", "true"：默认值为 false，表示绑卡完成后跳回您的页面，当值为为空时同理。值为 true 表示绑卡完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的绑卡结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 notifyVaulting 或 inquireVaulting 接口返回结果为准。
  3. 实现  AMSPaymentProtocol 的协议，用于后续流程中对应事件发生时的处理，包含以下方法：
    • ​onEventCallback：收银台绑卡事件回调函数，返回事件码（eventCode）和事件具体信息（eventResult）。
  4. 实现 AMSLogProtocol 的协议，用于管理日志输出，包含以下方法：
    • ​logWithName：默认输出日志的回调函数。
创建 SDK 实例的代码示例：
1#import <AMSComponent/AMSComponent-Swift.h>
2
3AMSVaultingConfiguration *componentConfig = [AMSVaultingConfiguration new];
4componentConfig.locale = @"en_US";
5// sandbox变更设置沙箱环境，不设置为线上正式环境
6NSDictionary *options = @{@"sandbox": @"true",
7                          @"notRedirectAfterComplete": @"true"
8                          };
9componentConfig.options = options;
10
11
12[[AMSVaulting shared] initConfiguration:componentConfig];
13[AMSVaulting shared].paymentDelegate = self;
14[AMSVaulting shared].loggerDelegate = self;
15
16[[AMSVaulting shared] createComponent:vaultingSessionData];
17
18#pragma AMSPaymentProtocol
19- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
20{
21    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
22}
23
24#pragma AMSLogProtocol
25- (void)logWithName:(NSString *)name parameter:(NSDictionary<NSString *,id> *)parameter
26{
27    NSLog(@"name%@ parameter%@", name, parameter);
28}
3

发起 createVaultingSession 请求

商户服务端

商户客户端自行监听 添加卡 按钮的点击事件。当买家选择支付方式并点击绑卡按钮后，商户服务端向 APO 服务器发起 createVaultingSession 请求。一旦接收到 createVaultingSession 请求的响应，将响应中的 vaultingSessionData 值用于步骤四。

如果您需要在卡资产绑定完成后自动重定向买家到您的页面，通过 createVaultingSession 接口中的 redirectUrl 字段传入跳转地址。如果您希望通过客户端事件码自行控制绑卡完成后续流程，则无需传入该字段，并通过 onEventCallback 监听绑卡结果事件码。

注意：客户端返回的绑卡结果事件码仅用于客户端页面的跳转操作参考，绑卡状态的更新请以服务端 createVaultingSession 接口为准。

资产绑定会话创建请求示例
1{
2  "paymentMethodType": "CARD",
3  "vaultingRequestId":"vaultingRequestId_001",
4  "vaultingNotificationUrl": "https://www.example.com.sg",
5  "redirectUrl": "https://www.example.com"
6}
4

使用实例对象中的 createComponent 创建绑卡要素收集组件:

商户客户端
  • 使用 sessionData 参数创建配置对象: 将 createVaultingSession 请求的响应中获取的 vaultingSession Data 字段的完整数据传入 sessionData 参数。
  • 调用 createComponent() 函数创建绑卡要素收集组件。

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

调用 createComponent() 示例：
1[[AMSVaulting shared] createComponent:sessionData];
2//销毁组件
3[[AMSVaulting shared] onDestroy];
5

获取绑卡结果

商户服务端

当绑卡成功后，支付宝会通过 notifyVaulting 发送异步通知到您在资产创建会话创建接口里传入的通知接收地址。若您收到支付宝的异步通知，需要您在返回中按照示例代码格式返回响应。同时，您需要更新您系统内买家的绑卡状态，建议在您的绑卡管理页根据通知里的卡信息展示对应的脱敏卡号。

 

参考信息
事件码

SDK 提供的错误码如下：

  • SDK_INTERNAL_ERROR：SDK 内部错误。请联系 Antom 技术支持。
  • SDK_CREATEPAYMENT_PARAMETER_ERROR：createComponent 函数传入参数异常，请检查参数是否正确后更换 vaultingRequestId 重试请求。
  • SDK_INIT_PARAMETER_ERROR：AMSVaulting 函数传入参数异常。请检查参数是否正确后更换 vaultingRequestId 重试请求。
  • SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Antom 技术支持。
  • SDK_ABNORMAL_RENDERING_DATA：渲染数据异常。请重试初始化流程或联系技术支持排查。
  • SDK_SUBMIT_NETWORK_ERROR：网络原因，导致接口调用失败。在 submit 函数提交中可能会出现。请买家再尝试重新提交。

 

SDK 提供的状态码如下：

  • SDK_CALL_URL_ERROR：跳转商户页面失败。检查跳转商户链接是否可以正常可访问。若回跳 URL 可正常访问，请联系 Antom 技术支持。
  • SDK_CALL_URL_SUCCESS：跳转商户页面成功。无需后续操作。
  • SDK_FORM_VERIFICATION_FAILED：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误。商户也可以通过文案引导用户输入正确信息。
  • SDK_DUPLICATE_SUBMISSION_BEHAVIOR：表单重复提交。商户可以通过文案提示用户，无需重复点击提交。

 

    SDK 提供的绑卡结果码如下：

    • SDK_ASSET_BINDING_FAIL：绑卡失败。建议您根据 vaultingResultCode 错误码提示信息，并重新引导用户绑卡。
    • SDK_ASSET_BINDING_SUCCESSFUL：绑卡成功，需要注销SDK。建议重定向到绑卡结果页。
    • SDK_ASSET_BINDING_ERROR：绑卡异常。建议您等待绑卡结果通知或重新引导用户绑卡。

     

    SDK 查询服务端结果码（result.resultCode）：

    结果码

    值

    消息

    建议

    SUCCESS

    S

    Success

    无需进一步操作。

    PROCESS_FAIL

    F

    A general business failure occurred.

    通常需要人工确认该问题。 建议您联系 Antom 技术支持解决该问题。

    UNKNOWN_EXCEPTION

    U

    An API call has failed, which is caused by unknown reasons.

    无。

     

     

    SDK 查询服务端绑卡结果码（vaultingResultcode）：

    结果码

    值

    消息

    建议

    PROCESS_FAIL

    F

    A general business failure occurred.

    通常需要人工确认该问题。 建议您联系 Antom 技术支持解决该问题。

     

    绑卡结果事件码处理示例：
    1#import <AMSComponent/AMSComponent-Swift.h>
2
3#pragma AMSPaymentProtocol
4- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
5{
6    if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_SUCCESSFUL"]) {
7      // 绑卡成功，需要注销SDK。建议重定向到绑卡结果页。
8    } else if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_FAIL"]) {
9      // 绑卡失败。建议您根据 vaultingResultCode 错误码提示信息，并重新引导用户绑卡。
10    } else if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_ERROR"]) {
11      // 绑卡异常。建议您等待绑卡结果通知或重新引导用户绑卡。
12    }
13    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
14}
    绑卡结果示例：
    1{
2  "code": "SDK_ASSET_BINDING_SUCCESSFUL",  // 前端事件码 
3  "result": {
4    "resultStatus": "S", 
5    "resultCode": "SUCCESS", 
6    "resultMessage": "Success" 
7  }
8}
    集成关键步骤代码示例

    以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 createVaultingSession 接口的步骤示例，需要您自行处理服务端接口的调用。

    1#import <AMSComponent/AMSComponent-Swift.h>
2
3// 步骤一：创建AMSVaultingConfiguration类型
4AMSVaultingConfiguration *componentConfig = [AMSVaultingConfiguration new];
5componentConfig.locale = @"en_US";
6
7// sandbox变更设置沙箱环境，不设置为线上正式环境
8// sandbox变更设置沙箱环境，不设置为线上正式环境
9NSDictionary *options = @{@"sandbox": @"true",
10                          @"notRedirectAfterComplete": @"true"
11                          };
12componentConfig.options = options;
13[[AMSVaulting shared] setConfiguration:componentConfig];
14
15// 设置收银台回调监听 
16[AMSVaulting shared].paymentDelegate = self;
17[AMSVaulting shared].loggerDelegate = self;
18
19// 步骤二：服务端创建调用资产绑定会话接口，获取vaultingSessionData
20
21
22// 步骤三：创建渲染卡组件
23[[AMSVaulting shared] createComponent:vaultingSessionData];
24
25#pragma AMSPaymentProtocol
26- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
27{
28    if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_SUCCESSFUL"]) {
29      // 绑卡成功，需要注销SDK。建议重定向到绑卡结果页。
30    } else if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_FAIL"]) {
31      // 绑卡失败。建议您根据 vaultingResultCode 错误码提示信息，并重新引导用户绑卡。
32    } else if ([eventCode isEqualToString:@"SDK_ASSET_BINDING_ERROR"]) {
33      // 绑卡异常。建议您等待绑卡结果通知或重新引导用户绑卡。
34    }
35    
36    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
37}
38
39#pragma AMSLogProtocol
40- (void)logWithName:(NSString *)name parameter:(NSDictionary<NSString *,id> *)parameter
41{
42    NSLog(@"name%@ parameter%@", name, parameter);
43}