Android

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

集成准备

在您开始集成前，请阅读集成指南及 API 概述文档，了解服务端 API 的集成步骤及 API 的调用注意事项，并确保已完成以下预配置及环境准备工作：

在开发者中心获得 client ID
在开发者中心完成密钥配置
已安装最新版本的 Android Studio
目标运行环境须为 API 级别 19 及更高版本
使用 Gradle 4.1 及以上版本
使用 AndroidX
配置物理机或模拟器，用于运行您的应用

关键集成步骤

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

引入 SDK 包。

商户客户端

在开发者中心下载资源包后，完成以下步骤：

将解压得到的 .aar 编译文件放置到工程的 libs 文件中。
在当前工程应用中的 build.gradle 文件中声明 .aar 编译文件的引用。
在 build.gradle 文件中添加依赖信息。

在 build.gradle 文件中添加依赖信息：

1dependencies {
2
3    // Configure the SDK aar package
4    implementation(name: 'ams-component-sdk-release', ext: 'aar')
5    // Use version 1.3.0 or later
6    implementation 'com.google.android.material:material:1.3.0'
7}

通过 AMSCheckout() 构造函数创建 SDK 实例：

商户客户端

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

创建 configuration 对象：必传，Object 类型。包含所有配置参数：
- locale: 选传，String 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器多语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值，如果传入的值不是以下四种，将提供英语页面：
  - locale("en", "US")：英语
  - locale("pt", "BR")：葡萄牙语
  - locale("ko", "KR")：韩语
  - locale("es", "ES")：西班牙语
- envType: 必传，AMSEnvTypeEnum 类型。用于传入环境参数，支持的值包括：
  - SANDBOX：沙箱环境
  - PROD：生产环境
创建 OnCheckoutListener 接口的实例，用于后续流程中对应事件发生时的处理，包含以下方法：
- OnPaymentEventCallback(): 必传。收银台支付事件回调函数，返回事件码（eventCode）和事件信息（message）。
将 OnCheckoutListener 接口的实例设置到 configuration 实例中，用于执行事件回调。
实例化 AMSCheckout 。

创建 SDK 实例：

1AMSComponentConfiguration configuration = new AMSComponentConfiguration(new Locale("en", "US"), AMSEnvTypeEnum.PROD);
2
3configuration.setOnCheckoutListener(new OnCheckoutListener() {
4    @Override
5    public void onPaymentEventCallback(String eventCode, String message) {
6        String msg = String.format("onEvent: eventCode=%s,message=%s", eventCode, message);
7        Log.i(TAG, msg);
8        Toast.makeText(SessionComponentActivity.this, msg, Toast.LENGTH_LONG).show();
9    }
10});
11
12AMSComponentCheckout checkout = new AMSComponentCheckout.Builder(SessionComponentActivity.this, configuration).build();

向 Alipay 服务器发起 支付会话创建 请求。

商户服务端

买家在支付方式选择页选择卡支付方式后，商户客户端自行实现支付按钮的点击事件监听。当监听到支付按钮被用户点击后，商户服务端需向 Alipay 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后，将响应中的 paymentSessionData 参数值用于步骤 4 。

注意：在调用支付会话创建 接口时，请求参数 paymentRedirectUrl 的值需要使用您提供的支付完成后跳转页面对应的 URL Scheme 。

以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：

1{
2  "order": {
3    "buyer": {
4      "buyerName": {
5        "firstName": "*****",
6        "fullName": "D***u",
7        "lastName": "Liu",
8        "middleName": "Skr"
9      },
10      "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
11      "referenceBuyerId": "tony.c"
12    },
13    "goods": [{
14      "goodsBrand": "AMSDM",
15      "goodsCategory": "card/ssr/adc",
16      "goodsName": "Goods No.1",
17      "goodsQuantity": "1",
18      "goodsSkuName": "SKU1",
19      "goodsUnitAmount": {
20        "currency": "USD",
21        "value": "10000"
22      },
23      "goodsUrl": "HangZhou LeiFenTa",
24      "referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
25    }],
26    "orderAmount": {
27      "currency": "BRL",
28      "value": "2129"
29    },
30    "orderDescription": "AMSDM_GIFT",
31    "referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
32  },
33  "paymentAmount": {
34    "currency": "BRL",
35    "value": "2129"
36  },
37  "paymentFactor": {
38    "isAuthorization": true
39  },
40  "paymentMethod": {
41    "paymentMethodType": "CARD",
42    "paymentMethodMetaData":{
43        "paymentMethodRegion":"BR"
44    }
45  },
46  "paymentNotifyUrl": "https://www.google.com.sg",
47  "paymentRedirectUrl": "https://www.baidu.com",
48  "paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
49  "productCode": "CASHIER_PAYMENT",
50  "settlementStrategy": {
51    "settlementCurrency": "USD"
52  },
53  "enableInstallmentCollection":"true"
54}

支付会话创建请求的响应示例：

1{
2  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
3  "paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
4  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
5  "result": {
6    "resultCode": "SUCCESS",
7    "resultMessage": "success.",
8    "resultStatus": "S"
9  }
10}

使用实例对象中的 createComponent() 创建支付要素收集组件。

商户客户端

调用 createComponent() 并传入以下参数:

activity: 必传。Activity 类型的一个对象，用于包含当前页面的上下文参数信息。
paymentType: 必传。String 类型。支持的值为 CARD 。
paymentSessionData：必传。String类型。将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 paymentSessionData 参数。
appearance：必传。AMSPaymentAppearance类型。此参数用于扩展用途，当前传入值为 null 。

创建配置对象：

1checkout.createComponent(activity, "CARD", paymentSessionData, null);

参考信息

事件码

SDK 提供的事件码如下：

SDK_INTERNAL_ERROR：加载浮层收银台失败。
SDK_CALL_URL_ERROR：此事件码代表以下事件信息中的一种情况：
- 跳转商户页面失败。
- 调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。

SDK_CREATECOMPONENT_ERROR：创建卡组件失败，需使用正确参数再次调用 createComponent()。

集成代码关键步骤示例

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

1import com.alipay.ams.component.sdk.callback.OnCheckoutListener;
2import com.alipay.ams.component.sdk.model.AMSEnvTypeEnum;
3import com.alipay.ams.component.sdk.payment.AMSComponentCheckout;
4import com.alipay.ams.component.sdk.payment.AMSComponentConfiguration;
5
6// 步骤一：创建AMSComponentConfiguration类型
7AMSComponentConfiguration configuration = new AMSComponentConfiguration();
8configuration.setLocale(new Locale("en", "US"));
9configuration.setEnvTypeEnum(AMSEnvTypeEnum.PROD);
10
11// 设置收银台回调监听
12configuration.setOnCheckoutListener(new OnCheckoutListener() {
13    @Override
14    public void onPaymentEventCallback(String eventCode, String message) {
15        Log.e(TAG, "onPaymentEventCallback eventCode=" + eventCode + " message=" + message);
16        Toast.makeText(SessionComponentActivity.this,
17                       "eventCode=" + eventCode +
18                       " message=" + message, Toast.LENGTH_LONG).show();
19    }
20});
21
22// 创建AMSComponentCheckout实例化
23AMSComponentCheckout checkout = new AMSComponentCheckout.Builder(this, configuration).build();
24
25// 提交支付
26public void handleSubmit(View view) {
27    // 步骤二：服务端创建调用支付会话接口，获取paymentSessionData
28    String paymentSessionData = requestSessionData();
29
30    // 步骤三：创建渲染卡组件
31    // 最佳实践
32    checkout.createComponent(this, "CARD", paymentSessionData, null);
33}