Android
此章节为您提供 Android 端卡支付 SDK 的集成指南,帮助您快速开始手机 app 内的支付相关页面渲染。
集成准备
关键集成步骤
请根据以下步骤完成集成:
1
引入 SDK 包。
商户客户端
在开发者中心下载资源包后,完成以下步骤:
- 将解压得到的 .aar 编译文件放置到工程的 libs 文件中。
-
在当前工程应用中的 build.gradle 文件中声明 .aar 编译文件的引用。
- 在 build.gradle 文件中添加依赖信息。
在 build.gradle 文件中添加依赖信息:
dependencies {
// Configure the SDK aar package
implementation(name: 'ams-component-sdk-release', ext: 'aar')
// Use version 1.3.0 or later
implementation 'com.google.android.material:material:1.3.0'
}2
通过 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:生产环境
- locale: 选传,String 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器多语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值,如果传入的值不是以下四种,将提供英语页面:
- 创建
OnCheckoutListener接口的实例,用于后续流程中对应事件发生时的处理,包含以下方法:OnPaymentEventCallback(): 必传。收银台支付事件回调函数,返回事件码(eventCode)和事件信息(message)。
- 将
OnCheckoutListener接口的实例设置到 configuration 实例中,用于执行事件回调。 - 实例化 AMSCheckout 。
创建 SDK 实例:
AMSComponentConfiguration configuration = new AMSComponentConfiguration(new Locale("en", "US"), AMSEnvTypeEnum.PROD);
configuration.setOnCheckoutListener(new OnCheckoutListener() {
@Override
public void onPaymentEventCallback(String eventCode, String message) {
String msg = String.format("onEvent: eventCode=%s,message=%s", eventCode, message);
Log.i(TAG, msg);
Toast.makeText(SessionComponentActivity.this, msg, Toast.LENGTH_LONG).show();
}
});
AMSComponentCheckout checkout = new AMSComponentCheckout.Builder(SessionComponentActivity.this, configuration).build();买家在支付方式选择页选择卡支付方式后,商户客户端自行实现支付按钮的点击事件监听。当监听到支付按钮被用户点击后,商户服务端需向 Alipay 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后,将响应中的 paymentSessionData 参数值用于步骤 4 。
注意:在调用支付会话创建 接口时,请求参数 paymentRedirectUrl 的值需要使用您提供的支付完成后跳转页面对应的 URL Scheme 。
以下支付会话创建请求示例,仅包含了必传字段及部分选传字段:
{
"order": {
"buyer": {
"buyerName": {
"firstName": "*****",
"fullName": "D***u",
"lastName": "Liu",
"middleName": "Skr"
},
"buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
"referenceBuyerId": "tony.c"
},
"goods": [{
"goodsBrand": "AMSDM",
"goodsCategory": "card/ssr/adc",
"goodsName": "Goods No.1",
"goodsQuantity": "1",
"goodsSkuName": "SKU1",
"goodsUnitAmount": {
"currency": "USD",
"value": "10000"
},
"goodsUrl": "HangZhou LeiFenTa",
"referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
}],
"orderAmount": {
"currency": "BRL",
"value": "2129"
},
"orderDescription": "AMSDM_GIFT",
"referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
},
"paymentAmount": {
"currency": "BRL",
"value": "2129"
},
"paymentFactor": {
"isAuthorization": true
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData":{
"paymentMethodRegion":"BR"
}
},
"paymentNotifyUrl": "https://www.google.com.sg",
"paymentRedirectUrl": "https://www.baidu.com",
"paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
"productCode": "CASHIER_PAYMENT",
"settlementStrategy": {
"settlementCurrency": "USD"
},
"enableInstallmentCollection":"true"
}支付会话创建请求的响应示例:
{
"paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
"paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
"paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}4
使用实例对象中的 createComponent() 创建支付要素收集组件。
商户客户端
调用 createComponent() 并传入以下参数:
- activity: 必传。Activity 类型的一个对象,用于包含当前页面的上下文参数信息。
- paymentType: 必传。String 类型。支持的值为
CARD。 - paymentSessionData:必传。String类型。将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 paymentSessionData 参数。
- appearance:必传。AMSPaymentAppearance类型。此参数用于扩展用途,当前传入值为
null。
创建配置对象:
checkout.createComponent(activity, "CARD", paymentSessionData, null);参考信息
事件码
SDK 提供的事件码如下:
-
SDK_INTERNAL_ERROR:加载浮层收银台失败。 -
SDK_CALL_URL_ERROR:此事件码代表以下事件信息中的一种情况:-
跳转商户页面失败。
-
调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。
-
-
SDK_CREATECOMPONENT_ERROR:创建卡组件失败,需使用正确参数再次调用createComponent()。
集成代码关键步骤示例
以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例,需要您自行处理服务端接口的调用。
import com.alipay.ams.component.sdk.callback.OnCheckoutListener;
import com.alipay.ams.component.sdk.model.AMSEnvTypeEnum;
import com.alipay.ams.component.sdk.payment.AMSComponentCheckout;
import com.alipay.ams.component.sdk.payment.AMSComponentConfiguration;
// 步骤一:创建AMSComponentConfiguration类型
AMSComponentConfiguration configuration = new AMSComponentConfiguration();
configuration.setLocale(new Locale("en", "US"));
configuration.setEnvTypeEnum(AMSEnvTypeEnum.PROD);
// 设置收银台回调监听
configuration.setOnCheckoutListener(new OnCheckoutListener() {
@Override
public void onPaymentEventCallback(String eventCode, String message) {
Log.e(TAG, "onPaymentEventCallback eventCode=" + eventCode + " message=" + message);
Toast.makeText(SessionComponentActivity.this,
"eventCode=" + eventCode +
" message=" + message, Toast.LENGTH_LONG).show();
}
});
// 创建AMSComponentCheckout实例化
AMSComponentCheckout checkout = new AMSComponentCheckout.Builder(this, configuration).build();
// 提交支付
public void handleSubmit(View view) {
// 步骤二:服务端创建调用支付会话接口,获取paymentSessionData
String paymentSessionData = requestSessionData();
// 步骤三:创建渲染卡组件
// 最佳实践
checkout.createComponent(this, "CARD", paymentSessionData, null);
}