银行卡支付（Android）

2024-09-12 07:33

Antom SDK 是一个预构建的用户界面组件，用于收集银行卡信息并为您处理 3D 验证流程。集成此组件不需要您具备 PCI 资格，非常适合那些希望委托 Antom 来收集银行卡信息的用户。

用户体验

以下图表展示了在应用程序中支付的用户流程：

支付流程

对于每种支付方式，支付流程包括以下步骤：

WAP）-中@3x.png

用户进入结账页面。

创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 支付会话创建（收银台）接口获取支付会话。
调用客户端SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码显示、验证等流程。
获取支付结果。
通过以下两种方法之一获取支付结果：

异步通知：在 支付会话创建（收银台）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 支付通知 向您发送异步通知。
同步查询：调用 支付结果查询 接口来查询支付状态。

获取请款结果。
对于银行卡支付，通过以下两种方法之一获取请款结果：

异步通知：在 支付会话创建（收银台）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付请求成功或过期时，Antom 会通过 请款通知（收银台）向您发送异步通知。
同步查询：调用 支付结果查询 接口来查询支付请求状态。

集成步骤

通过以下步骤开始集成：

创建支付会话
创建并调用 SDK
获取支付结果
获取请款结果

步骤 1：创建支付会话服务端

当买家选择 Antom 提供的支付方式时，您需要收集关键信息，如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接，调用 支付会话创建（收银台）接口来创建支付会话，并将支付会话返回给客户端。

Antom 提供了多种语言的服务器端接口库。以下代码以 Java 为例，您需要安装 Java 6 或更高版本。

安装接口库

您可以在 GitHub 上找到最新版本。

copy
<dependency>
    <groupId>com.alipay.global.sdk</groupId>
    <artifactId>global-open-sdk-java</artifactId>
    <version>2.0.29</version>
</dependency>

初始化请求实例

创建一个单例资源，以向 Antom 发起请求。

copy
import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;

import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;
import com.alipay.global.api.model.constants.EndPointConstants;

public class Sample {
    public static final String        CLIENT_ID            = "";
    public static final String        ANTOM_PUBLIC_KEY     = "";
    public static final String        MERCHANT_PRIVATE_KEY = "";

    private final static AlipayClient CLIENT               = new DefaultAlipayClient(
            EndPointConstants.SG, MERCHANT_PRIVATE_KEY, ANTOM_PUBLIC_KEY, CLIENT_ID);

}

创建支付会话

创建支付会话涉及以下参数：

参数名称	是否必需	描述
productCode	✅	代表所使用的支付产品，根据合同规定。对于收银台支付，值设置为 `CASHIER_PAYMENT`。
paymentRequestId	✅	商家为识别支付请求而分配的专属 ID。
paymentAmount	✅	您请求在订单货币中接收的支付金额。
paymentMethod	✅	由商户或收单机构用来收集支付的支付方式。
paymentRedirectUrl	✅	支付完成后，买家被重定向到的商户页面链接。
order	✅	包括买家、商户、商品、金额、配送信息和购买环境的订单信息。
paymentNotifyUrl		支付结果通知地址，可通过接口传递，也可通过门户设置为固定值。
settlementStrategy		支付请求的结算策略。

以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 支付会话创建（收银台）。

调用支付会话创建接口的示例代码

以下示例代码展示了如何调用 支付会话创建（收银台）接口：

copy
public static void createCardPaymentSession() {
    AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
    alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

    // replace with your paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

    // set amount
    Amount amount = Amount.builder().currency("SGD").value("4200").build();
    alipayPaymentSessionRequest.setPaymentAmount(amount);

    // set paymentMethod
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("CARD").build();
    alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

    // set auth capture payment mode
    PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
    alipayPaymentSessionRequest.setPaymentFactor(paymentFactor);

    // replace with your orderId
    String orderId = UUID.randomUUID().toString();

    // set buyer info
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // set order info
    Order order = Order.builder().referenceOrderId(orderId)
        .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
    alipayPaymentSessionRequest.setOrder(order);

    // replace with your notify url
    alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

    // replace with your redirect url
    alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
    try {
        alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

以下代码显示了一个请求报文的示例：

copy
{
  "order": {
    "buyer": {
      "referenceBuyerId": "yourBuyerId"
    },
    "orderAmount": {
      "currency": "SGD",
      "value": "4200"
    },
    "orderDescription": "antom testing order",
    "referenceOrderId": "referenceOrderId01"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodType": "CARD"
  },
  "paymentNotifyUrl": "https://www.yourNotifyUrl.com",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "productCode": "CASHIER_PAYMENT"
}

以下代码显示了一个响应的示例，其中包含以下参数：

paymentSessionData ：需要返回给前端的支付会话数据
paymentSessionExpiryTime ：支付会话的过期时间。

copy
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

常见问题
问：请求参数的值可以使用中文字符吗？
答：为了避免特定支付方式的兼容性问题，请求中的字段请勿使用中文字符。

问：如何设置接收支付通知的链接？
答：在 支付会话创建（收银台）接口中指定 paymentNotifyUrl 字段，以接收支付结果的异步通知（支付通知），或者在 Antom Dashboard 中配置接收链接。如果请求和 Antom Dashboard 中都指定了链接，请求中的值优先。

步骤 2：创建并调用 SDK 客户端

Antom SDK 是用于处理支付流程的组件。为了收集信息、在应用间切换以及根据 支付会话创建（收银台）接口中指定的支付方式显示二维码，您需要通过创建支付会话来启动 SDK。

当买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 SDK。

安装

版本要求：目标至少为 Android 4.4（API level 19）或更高版本。

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

初始化 SDK

使用 AMSCashierPayment 创建 SDK 实例并指定基本配置。创建配置对象包括以下方法：

参数名称	是否必需	描述
setLocale		用于传递语言信息。有效值如下所示。您可以根据支付方式的地区选择要传递的值。如果传递其他值，默认使用本地语言： `en_US`：英语 `pt_BR`：葡萄牙语 `ko_KR`：韩语 `es_ES`：西班牙语 `ms_MY`：马来语 `in_ID`：印尼语 `tl_PH`：他加禄语 `th_TH`：泰语 `vi_VN`：越南语 `fr_FR`：法语 `nl_NL`：荷兰语 `it_IT`：意大利语 `de_DE`：German `zh_CN`：简体中文 `zh_HK`：繁体中文
setOption		用于指定是否使用默认加载模式和沙箱环境。有效值包括： `"sandbox", "true"`：沙箱环境 `"sandbox", "false"`：生产环境 `"showLoading", "true"`：使用默认加载模式。 `"showLoading", "false"`：不使用默认加载模式。
setOnCheckoutListener		创建一个结账监听器接口的实例，用于后续流程中的事件处理。该接口包含以下方法： `onEventCallback`：必需。一个回调函数，用于监听结账页面上的支付事件，返回 eventCode 和 eventResult。

以下示例代码展示了如何初始化 SDK：

copy
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
configuration.setOption("showLoading", "true");
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
configuration.setOption("sandbox", "true");
// Configure whether the payment button is rendered by the SDK component.
configuration.setOption("showSubmitButton", "true");
// Set the callback to monitor payment events on the checkout page.
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
    }
});
// Instantiate AMSCashierPayment.
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

调用 SDK

调用 createComponent 方法：

参数名称	是否必需	描述
sessionData	✅	使用 sessionData 参数创建配置对象：将通过支付会话创建（收银台）接口在响应中获取的完整 paymentSessionData 参数传递给 sessionData 。

在以下情况下调用 onDestroy 方法释放 SDK 组件资源：

当买家离开结账页面时，释放 支付会话创建（收银台）中创建的组件资源。
当买家发起多次支付时，释放之前 支付会话创建（收银台）中创建的组件资源。

以下示例代码展示了如何调用 SDK：

copy
checkout.createComponent(activity, sessionData);

//Free SDK component resources
checkout.onDestroy();

显示支付结果

支付结果将通过 onEventCallback 函数返回。这里的支付结果仅用于前端显示，最终订单状态以服务器端为准。您需要通过 onEventCallback 返回的数据自定义每个支付结果的处理流程。

以下是 onEventCallback 返回的支付结果可能的事件代码。

事件代码	消息	解决方案
SDK_PAYMENT_SUCCESSFUL	支付成功。	建议将买家重定向到支付结果页面。
SDK_PAYMENT_PROCESSING	支付正在处理中。	建议您检查在`onEventCallback`结果数据中 paymentResultCode 的值以获取详细信息。根据提供的信息，引导买家重新尝试支付。
SDK_PAYMENT_FAIL	支付失败。	建议您检查在`onEventCallback`结果数据中 paymentResultCode 的值以获取详细信息。根据提供的信息，引导买家重新尝试支付。
SDK_PAYMENT_CANCEL	买家在未提交订单的情况下退出了支付页面。	在有效期内，可以使用 paymentSessionData 重新调用SDK；如果已过期，需要重新请求paymentSessionData。
SDK_PAYMENT_ERROR	支付状态异常。	建议您检查在`onEventCallback`结果数据中 paymentResultCode 的值以获取详细信息。根据提供的信息，引导买家重新尝试支付。

以下示例代码展示了如何处理 onEventCallback 事件：

copy
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
configuration.setOption("showLoading", "true");
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
configuration.setOption("sandbox", "true");
// Configure whether the payment button is rendered by the SDK component.
configuration.setOption("showSubmitButton", "true");
// Set the callback to monitor payment events on the checkout page.
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());

        if (!TextUtils.isEmpty(eventCode)) {
            if ("SDK_PAYMENT_SUCCESSFUL".equals(eventCode)) {
                // Payment was successful. Redirect buyers to the payment result page.
            } else if ("SDK_PAYMENT_PROCESSING".equals(eventCode)) {
                // Payment was being processed. Guide buyers to retry the payment based on the provided information.
            } else if ("SDK_PAYMENT_FAIL".equals(eventCode)) {
                // Payment failed. Guide buyers to retry the payment based on the provided information.
            }else if ("SDK_PAYMENT_CANCEL".equals(eventCode)) {
                // Guide buyers to retry the payment.
            } else if ("SDK_PAYMENT_ERROR".equals(eventCode)) {
                // The payment status was abnormal. Guide buyers to retry the payment based on the provided information.
            } else if ("SDK_FORM_VERIFICATION_FAILED".equals(eventCode)) {
                // The SDK displays a form error code on the element collection page if the form submission fails.
            }
        }
    }
});
// Instantiate AMSCashierPayment.
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

步骤 3：获取支付结果服务端

在买家完成支付或支付超时后，Antom 会通过服务器交互将相应的支付结果发送给您，您可以通过以下方法之一获取支付结果：

接收异步通知
查询结果

接收异步通知

支付成功或失败时，Antom会向您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（支付通知）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。

Antom允许您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码展示了通知请求的示例：

copy
{
  "actualPaymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "cardInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentCreateTime": "2024-01-01T00:00:00+08:00",
  "paymentId": "20240101123456789XXXX",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

如何验证通知的签名并做出响应，请参阅签名与验签。

常见问题
问：何时会发送通知？
答：这取决于支付是否完成：
如果支付成功完成，Antom 通常会在3到5秒内发送异步通知。对于某些支付方式，如柜台支付（OTC），通知可能会稍有延迟。
如果支付未完成，Antom 需要先关闭订单，然后才会发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为14分钟。
问：异步通知会被重新发送吗？
答：是的，对于以下情况，异步通知会在 24 小时内自动重新发送：
如果由于网络原因未收到异步通知。
如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式对通知做出响应。
通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。

问：在响应异步通知时，我需要添加数字签名吗？
答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。

问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
result ：表示订单的支付结果。
paymentRequestId ：用于咨询、取消和对账的支付请求 ID。
paymentId ：表示由 Antom 生成的支付订单 ID，用于退款和对账。
paymentAmount ：表示支付金额。

查询结果

您可以调用 支付结果查询 接口来发起对订单结果的查询。

参数名称	是否必需	描述
paymentRequestId		由商户生成的支付请求 ID。

完整的参数集，请参考 支付结果查询 接口文档，获取全部参数及特定支付方式的额外要求。

以下示例代码展示了如何调用 支付结果查询 接口：

copy
public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

以下是请求报文的示例：

copy
{
  "paymentRequestId": "paymentRequestId01"
}

以下是响应报文的示例：

copy
{
  "authExpiryTime": "2024-01-08T00:01:00+08:00",
  "cardInfo": {
    "cardBrand": "MASTERCARD",
    "funding": "DEBIT",
    "issuingCountry": "US"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentId": "20240101123456789XXXX",
  "paymentMethodType": "CARD",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultCode": "SUCCESS",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "networkTransIdXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentResultMessage": "success",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

常见问题
问：我应该多久调用一次支付结果查询 接口？
答：以 2 秒的间隔持续调用 支付结果查询 接口，直到获取最终的支付结果或收到异步支付结果通知为止。

问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
result ：表示此 支付结果查询 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
SUCCESS和FAIL表示最终结果。
PROCESSING表示处理中。
paymentAmount ：表示支付的金额。

步骤 4：获取请款结果服务端

在买家完成请款或请款超时后，Antom 会通过服务器交互将相应的请款结果发送给您，您可以通过以下方法之一获取请款结果：

接收异步通知
查询结果

接收异步通知

当请款成功或失败时，Antom 会向您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（支付通知）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。

Antom允许您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码显示了成功的请款示例：

copy
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101123456789XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "fail.",
    "resultStatus": "F"
  }
}

以下代码显示了失败的请款示例：

copy
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101123456789XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "fail.",
    "resultStatus": "F"
  }
}

如何验证通知的签名并做出响应，请参阅签名与验签。

常见问题
问：异步通知会被重新发送吗？
答：是的，对于以下情况，异步通知将在 24 小时内自动重新发送：
如果您因网络原因未收到异步通知。
如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式进行响应。
通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔为：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时和 15 小时。

问：在响应异步通知时，我需要添加数字签名吗？
答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。

问：我需要使用通知中的哪些关键参数？
答：请注意以下关键参数：
result ：表示订单的请款结果。
notifyType ：通知类型为 CAPTURE_RESULT 。
paymentRequestId ：您生成的支付请求 ID，用于查询、取消和对账。
paymentId ：Antom 生成的支付订单 ID，用于退款和对账。
acquirerReferenceNo ：集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。

查询结果

您可以调用 支付结果查询 接口来发起对订单结果的查询。

参数名	是否必需	描述
paymentRequestId		由商户生成的支付请求ID。

有关完整参数集，请参阅 支付结果查询 接口，获取完整的参数列表以及某些支付方式的额外要求。

以下示例代码展示了如何调用 支付结果查询 接口：

copy
public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

以下是请求报文的示例：

copy
{
  "paymentRequestId": "paymentRequestId01"
}

请款状态的值

接口响应中的 transactions 字段值表示请款状态：

参数名称	描述
transactions.transactionType	值为 `CAPTURE`，表示请款状态。
transactions.transactionResult	请款状态

以下代码展示了成功的请款示例：

copy
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}

以下代码展示了失败的请款示例：

copy
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}

以下代码展示了处理中的请款示例：

copy
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}

常见问题
问：我应该多久调用一次支付结果查询 接口？
答：以 2 秒的间隔持续调用 支付结果查询 接口，直到获取最终的支付结果或收到异步支付结果通知。

示例代码

前端的完整示例代码：

copy
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
configuration.setOption("showLoading", "false");
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
configuration.setOption("sandbox", "true");
// Configure whether the payment button is rendered by the SDK component.
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        AlipayLog.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());

        if (!TextUtils.isEmpty(eventCode)) {
            if ("SDK_PAYMENT_SUCCESSFUL".equals(eventCode)) {
                // Payment was successful. Redirect buyers to the payment result page.
            } else if ("SDK_PAYMENT_PROCESSING".equals(eventCode)) {
                // Payment was being processed. Guide buyers to retry the payment based on the provided information.
            } else if ("SDK_PAYMENT_FAIL".equals(eventCode)) {
                // Payment failed. Guide buyers to retry the payment based on the provided information.
            }else if ("SDK_PAYMENT_CANCEL".equals(eventCode)) {
                // Guide buyers to retry the payment.
            } else if ("SDK_PAYMENT_ERROR".equals(eventCode)) {
                // The payment status was abnormal. Guide buyers to retry the payment based on the provided information.
            } else if ("SDK_END_OF_LOADING".equals(eventCode)) {
                // End your custom loading animation.
            }
        }
    }
});
// Instantiate AMSCashierPayment.
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

checkout.createComponent(activity, sessionData);

事件代码

可能会看到两种类型的事件代码：

状态代码：由组件运行时生命周期中的onEventCallback 返回。
错误代码：由组件初始化阶段的onEventCallback 或onError 返回。

类型	代码	描述	后续操作
状态代码	SDK_START_OF_LOADING	在创建支付组件时开始播放加载动画。	无需进一步操作。
状态代码	SDK_END_OF_LOADING	在创建支付组件时加载动画结束。	无需进一步操作。
错误代码	SDK_INTERNAL_ERROR	SDK 内部错误发生。	请联系 Antom 技术支持解决此问题。
	SDK_CREATEPAYMENT_PARAMETER_ERROR	传递给 `createComponent` 方法的参数不正确。	确保参数传递正确并重新发送请求。
	SDK_CALL_URL_ERROR	表示以下情况之一：跳转到商户页面执行失败。在您的支付会话创建（收银台）请求中，参数 paymentRedirectUrl 未传递或传递错误。	请联系 Antom 技术支持解决此问题。
	SDK_INTEGRATION_ERROR	未找到依赖项。	请确保已正确添加依赖项，然后重试集成过程。

银行卡支付（Android）

用户体验

支付流程

集成步骤

步骤 1：创建支付会话 服务端

安装接口库

初始化请求实例

创建支付会话

调用支付会话创建接口的示例代码

步骤 2：创建并调用 SDK 客户端

安装

初始化 SDK

调用 SDK

显示支付结果

步骤 3：获取支付结果 服务端

接收异步通知

查询结果

步骤 4：获取请款结果 服务端

接收异步通知

查询结果

请款状态的值

示例代码

事件代码

步骤 1：创建支付会话服务端

步骤 3：获取支付结果服务端

步骤 4：获取请款结果服务端