Android

此章节为您提供 Android 端独立绑卡 SDK 的集成指南，帮助您快速开始手机 App 内的绑卡相关页面渲染。

集成准备

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

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

集成步骤

请按照以下步骤完成集成：

集成 SDK 资源包

商户客户端

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

通过 AMSVaulting 构造函数创建 SDK 实例：

商户客户端

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

创建 configuration 对象：必传，Object 类型。包含所有配置参数：
- setLocale: 选传，String类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种多语言，如果传入的值不是以下几种，将提供英语页面：
  - "en", "US"：英语
  - "es", "ES"：西班牙语
  - "fr", "FR"：法语
  - "nl", "NL"：荷兰语
  - "it", "IT"：意大利语
  - "de", "DE"：德语
  - "zh", "CN"：简体中文
- setOption: 选传，用于设置是否使用沙箱环境，支持的值包括：
  - "sandbox", "true"：沙箱环境。
  - "sandbox", "false"：生产环境。
  - "showSubmitButton", "true"：配置由 SDK 组件渲染绑卡按钮。
  - "showSubmitButton", "false"：配置由商户渲染绑卡按钮，同时需要调用实例对象中 submit函数触发提交绑卡流程。
创建 OnCheckoutListener 接口的实例，用于后续流程中对应事件发生时的处理，包含以下方法：
- onEventCallback: 必传。收银台支付事件回调函数，返回事件码（eventCode）和事件信息（eventResult）。
将 OnCheckoutListener 接口的实例设置到 configuration 实例中，用于执行事件回调。
实例化 AMSVaulting。

创建 SDK 实例

1AMSVaultingConfiguration configuration = new AMSVaultingConfiguration();
2configuration.setLocale(new Locale("en", "US"));
3// 设置沙箱环境，不设置为线上正式环境
4configuration.setOption("sandbox", "true");
5// 配置是否由SDK组件渲染支付按钮
6configuration.setOption("showSubmitButton", "true");
7// 设置收银台回调监听
8configuration.setOnCheckoutListener(new OnCheckoutListener() {
9    @Override
10    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
11        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
12    }
13});
14// 创建AMSVaulting实例化
15AMSVaulting checkout = new AMSVaulting.Builder(activity, configuration).build();

发起 createVaultingSession 请求

商户服务端

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

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

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

1{
2  "paymentMethodType": "CARD",
3  "vaultingRequestId":"vaultingRequestId_001",
4  "vaultingNotificationUrl": "https://www.example.com.sg",
5  "redirectUrl": "https://www.example.com"
6}

渲染绑卡要素收集组件

商户客户端

使用实例对象中的 mountComponent 函数并传入以下参数:
- activity：必传。Activity 类型对象，用于包含当前页面的上下文参数信息。
- appearance：类型为 AMSPaymentAppearance
  - "showSubmitButton", "true"：配置由SDK组件渲染绑卡按钮。
  - "showSubmitButton", "false"：配置由商户渲染绑卡按钮，同时需要调用实例对象中 submit() 函数触发提交绑卡流程。
- sessionData：必传。String 类型。将资产绑定会话创建请求的响应中获取的 vaultingSessionData 字段的完整数据传入 mountComponent 的 sessionData 参数。
- parentViewGroup：必填，FrameLayout 类型，用于绑定视图关联到商户的页面布局，布局参数需要设置为wrap_content, SDK 会根据视图内部内容的大小自动调整视图宽高。
调用实例对象中的 submit() 函数：
1. 调用该函数，可触发绑卡提交流程，返回值为 Promise，返回特定事件码。这些事件码也会通过 onError 或 onEventCallback 等事件返回。
2. 如果您需要传入提前收集好的 billing address 信息用于 AVS 验证，您可配置如下参数通过 submit 函数传入。
  - billingAddress：选传，Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数
    - region：必传，String (2)。遵循 ISO 3166 标准的二位国家码。
    - state：选传，String (8)。州、国家或省名称。
    - city：选传，String (32)。城市、地区、郊区、城镇或村庄名称。
    - address1：选传，String (256)。地址行 1，例如街道地址、邮政信箱和公司名称。
    - address2：选传，String (256)。地址行 2，例如公寓、套房、单元和建筑物信息。
    - zipCode：选传，String (32)。邮政编码。

调用 mountComponent()

1// 触发渲染内嵌组件
2Map<String, Object> appearanceConfig = new HashMap<>();
3appearanceConfig.put("showSubmitButton", false);
4appearanceConfig.put("showSubmitLoading", true);
5AMSPaymentAppearance appearance = AMSPaymentAppearance.create(appearanceConfig);
6checkout.mountComponent(activity, appearance, sessionData, parentViewGroup);
7
8let dataString = '{"billingAddress":{"zipCode":"310000","region":"CN"}}';
9
10// 用户输入完成提交绑定
11checkout.submit(dataString);

卸载组件

商户客户端

调用实例对象中的 onDestroy() 函数，可以销毁已经创建的组件。如下情况下您需要卸载组件：

如果你的客户端设置了超时时间，到达所设置的超时时间时。
买家退出绑卡页面时。
您收到绑卡结果回调时。

注意：同一时间只能创建一个组件，如果需要使用不同 vaultingSessionData 或重新创建组件，需要先执行卸载函数。

调用 onDestroy()

1checkout.onDestroy();

获取绑卡结果

商户服务端

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

事件码

SDK 提供的错误码如下：

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

SDK 提供的状态码如下：

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

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

SDK 提供的绑卡结果事件码如下（code）：

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

SDK 查询服务端绑卡状态（vaultingStatus）：

SUCCESS: 表示绑卡成功。
FAIL: 表示绑卡失败。

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 技术支持解决该问题。

绑卡结果事件码处理示例：

1AMSVaultingConfiguration configuration = new AMSVaultingConfiguration();
2configuration.setLocale(new Locale("en", "US"));
3// 设置沙箱环境，不设置为线上正式环境
4configuration.setOption("sandbox", "true");
5// 配置是否由SDK组件渲染支付按钮
6configuration.setOption("showSubmitButton", "true");
7// 设置收银台回调监听
8configuration.setOnCheckoutListener(new OnCheckoutListener() {
9    @Override
10    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
11        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
12
13        if (!TextUtils.isEmpty(eventCode)) {
14            if ("SDK_ASSET_BINDING_SUCCESSFUL".equals(eventCode)) {
15                //绑卡成功，需要注销SDK。建议重定向到绑卡结果页。
16            } else if ("SDK_ASSET_BINDING_FAIL".equals(eventCode)) {
17                // 绑卡失败。建议您根据 vaultingResultCode 错误码提示信息，并重新引导用户绑卡。
18            } else if ("SDK_ASSET_BINDING_ERROR".equals(eventCode)) {
19                // 绑卡异常。建议您等待绑卡结果通知或重新引导用户绑卡。
20            }
21        }
22    }
23});
24// 创建AMSVaulting实例化
25AMSVaulting checkout = new AMSVaulting.Builder(activity, configuration).build();

绑卡结果示例：

1{
2  "code": "SDK_ASSET_BINDING_SUCCESSFUL",  // 前端事件码 
3  "result": {
4    "resultStatus": "S", 
5    "resultCode": "SUCCESS", 
6    "resultMessage": "Success" 
7  }
8}