Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Android

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

 

集成准备

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

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

 

关键集成步骤

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

1

集成 SDK 资源包。

商户客户端

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

 

 

2

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

商户客户端

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

  1. 创建 configuration 对象：必传，Object 类型。包含所有配置参数：
    • setLocale: 选传，String 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种语言，如果传入的值不是以下几种，将提供英语页面：​
      • en_US：英语
      • pt_BR：葡萄牙语
      • ko_KR：韩语
      • es_ES：西班牙语
      • fr_FR：法语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • zh_CN：中文简体
      • zh_HK：中文繁体
    • setOption: 选传，用于设置是否采用默认 loading 样式以及是否使用沙箱环境，支持的值包括：
      • "sandbox", "true"：沙箱环境
      • "sandbox", "false"：生产环境
      • "showLoading", "true"：使用默认 loading 样式
      • "showLoading", "false"：不使用默认 loading 样式
      • "notRedirectAfterComplete", "true"：默认值为 false，表示支付完成后跳回您的页面，当值为为空时同理。值为 true 表示支付完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 支付通知 或 支付结果查询 接口返回结果为准。
      • "merchantAppointmentParam"：选传，JSON String类型，用于自定义功能设置，包含以下参数：
        • storedCard：选传，Object 类型，用于已存卡情况下的自定义功能设置，包含以下参数：
          • needCVV：选传，Boolean 类型，默认值为 false，表示在支付过程中无需用户输入CVV校验，当值为空时同理。若设定该值为 true ，则表示在支付过程中需要用户输入CVV校验。
  2. 创建 OnCheckoutListener 接口的实例，用于后续流程中对应事件发生时的处理，包含以下方法：
    • OnEventCallback: 必传。收银台支付事件回调函数，返回事件码（eventCode）和事件信息（eventResult）。
  3. 将 OnCheckoutListener 接口的实例设置到 configuration 实例中，用于执行事件回调。
  4. 实例化 AMSCashierPayment。
创建 SDK 实例：
Java
Editor
3

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

商户服务端

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

对于已绑卡的卡令牌支付模式下您需要通过 paymentMethod.paymentMethodId 字段传入买家绑卡后 APO 返回给您的卡令牌，获取卡令牌方式如下：

  • 独立绑卡：通过 APO 向您发送的资产绑定结果通知中的 card.cardToken 字段获取卡令牌。
  • 非独立绑卡：通过 APO 向您发送的支付结果通知或主动查询支付结果的响应中的 paymentResultInfo.cardToken 字段获取卡令牌。

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

以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：
JSON：未绑卡
JSON：Token 支付
Editor
支付会话创建请求的响应示例：
JSON
Editor
4

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

商户客户端
  • 调用 createComponent() 并传入以下参数:
    • activity: 必传。Activity 类型的一个对象，用于包含当前页面的上下文参数信息。
    • sessionData：必传。String类型。将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。

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

创建配置对象：
Java
Editor
参考信息
事件码

SDK 提供的错误码如下：

  • SDK_INTERNAL_ERROR：SDK内部错误。请联系 Antom 技术支持。
  • SDK_CREATEPAYMENT_PARAMETER_ERROR：createComponent 函数传入参数异常。请检查参数是否正确并重新初始化组件。
  • SDK_INIT_PARAMETER_ERROR：AMSCashierPayment函数传入参数异常。请检查参数是否正确并重新实例化 SDK。
  • SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Antom 技术支持。
  • SDK_SUBMIT_NETWORK_ERROR：网络原因，导致接口调用失败。在 submit 函数提交中可能会出现。请提示用户再尝试重新提交。

 

SDK 提供的状态码如下：

  • SDK_START_OF_LOADING：创建组件时，loading 动画开始显示。当配置隐藏 loading，使用自定义动画时，可以在这个时机渲染自定义动画。
  • SDK_END_OF_LOADING：创建组件时，loading 动画结束显示。当配置隐藏 loading，使用自定义动画时，这个时机可以隐藏动画。
  • SDK_CALL_URL_ERROR：此事件码代表以下事件信息中的一种情况：
    • 跳转商户页面失败。
    • 跳转 3D 挑战页面失败。
    • 调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。

         Web/WAP 场景下跳转链接通常不会异常，建议您校验重定向链接。App 场景下，如果经常出现此异常请联系 Antom 技术支持，排查跳转或唤端问题。

  • SDK_CALL_URL_SUCCESS：跳转商户页面成功。
  • SDK_DUPLICATE_SUBMISSION_BEHAVIOR：表单重复提交。商户可以通过文案提示用户，无需重复点击提交。
  • SDK_PAYMENT_AUTHORIZATION_SUCCESSFUL：支付流程完成，如果配置了支付完成后不跳转功能，建议继续监听对应的支付事件码来处理后续流程。否则可以忽略此事件码，会重定向到您的支付结果页。
  • SDK_PAYMENT_CHALLENGE：触发 3D 挑战，发卡行需要进一步的购物者互动，然后才能验证付款。无需处理，SDK 会跳转挑战页面。

 

    SDK 提供的支付事件码和结果码如下：

    SDK 提供的支付事件码（code）：

    • SDK_PAYMENT_SUCCESSFUL：支付成功。建议您重定向到支付结果页。
    • SDK_PAYMENT_FAIL：支付失败。建议您根据 paymentResultCode 错误码提示信息，并重新引导支付。
    • SDK_PAYMENT_PROCESSING：支付处理中。建议您的服务端查询支付状态或等待支付结果通知。
    • SDK_PAYMENT_ERROR：支付状态异常。建议您的服务端查询支付状态或等待支付结果通知。
    • SDK_PAYMENT_CANCEL：买家未点击支付并关闭支付窗口。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
    • SDK_FORM_VERIFICATION_FAILED：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误码。

    SDK 查询服务端支付状态（paymentStatus）：

    • SUCCESS: 表示支付成功。
    • FAIL: 表示支付失败。
    • PROCESSING: 表示支付处理中。
    • CANCELLED: 表示支付已取消。
    • PENDING: 表示支付已完成，请等待最终支付结果通知。

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

    结果码

    值

    消息

    建议

    SUCCESS

    S

    Success

    -

    ORDER_NOT_EXIST

    F

    The order does not exist.

    建议重新下单。

    PAYMENT_IN_PROCESS

    U

    The payment is being processed.

    等待支付通知或主动查询结果。

    PROCESS_FAIL

    F

    A general business failure occurred.

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

    UNKNOWN_EXCEPTION

    U

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

    等待支付通知或主动查询结果。

    INQUIRY_PAYMENT_SESSION_FAILED

    F

    Failed to retrieve paymentSessionData, which may have expired or is in an unknown state.

     

    会话已过期。等待支付通知或主动查询结果。

    PAGE_ELEMENT_ILLEGAL

    U

    The payment information is incorrect.

    支付被拒绝，支付要素填写错误。

    SDK 查询服务端支付结果（paymentResultCode）：

    结果码

    值

    消息

    建议

    SUCCESS

    S

    Success

     

    -

    ACCESS_DENIED

    F

    Access is denied.

    权限不足。联系技术支持了解具体原因。

    CURRENCY_NOT_SUPPORT

    F

    The currency is not supported.

    币种不支持。联系 Antom 技术支持了解具体原因。

    FRAUD_REJECT

    F

    The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

    欺诈拒绝。如下情况下请联系技术支持：

    • 您需要申诉。
    • 买家两周内未收到退款。

    INVALID_CARD

    F

    The card is invalid. Maybe the credit card number cannot be identified, the card has no corresponding issuing bank, or the card number is in the wrong format.

    无效卡。建议换卡重试。

     

    INVALID_EXPIRY_DATE_FORMAT

    F

    The format of expiryYear or expiryMonth is wrong.

    卡的有效期不正确。建议检查卡有效期的填写格式。

    ISSUER_REJECTS_TRANSACTION

    F

    The issuing bank rejects the transaction.

    发卡行拒绝。建议换卡重试或联系发卡行。

    INVALID_MERCHANT_STATUS

    F

    The merchant status is abnormal because restrictions exist.

    商户状态异常。联系技术支持了解具体原因。

    MERCHANT_KYB_NOT_QUALIFIED

    F

    The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction.

    联系技术支持了解具体原因。

    NO_PAY_OPTIONS

    F

    The currency is not supported for the transaction.

    币种不支持。检查支付方式是否支持该币种，或支付方式和币种是否与合同中所签约一致。如有问题，联系技术支持了解具体原因。

    ORDER_IS_CLOSED

    F

    The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed.

    订单已经关闭。发起新的请求重试。

    PAYMENT_AMOUNT_EXCEED_LIMIT

    F

    The payment amount is greater than the maximum amount allowed by the contract or payment method.

    超过限制金额。检查支付金额是否超过限额或使用较低的金额重试。 联系支付宝技术支持了解具体支付限额。

    PAYMENT_COUNT_EXCEED_LIMIT

    F

    The maximum number of payments exceeds the limit that is specified by the payment method.

    超过限制使用次数。联系支付宝技术支持了解具体支付限额。

    PAYMENT_NOT_QUALIFIED

    F

    The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Auto Debit payment, or is forbidden to make a payment.

    商户无权限。联系技术支持了解具体原因。

    PROCESS_FAIL

    F

    A general business failure occurred.

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

    RISK_REJECT

    F

    The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

    风控拒绝。如果买家两周内未收到退款，请联系 Antom 技术支持。

    SUSPECTED_CARD

    F

    The card is suspected of fraud. For example, the card is stolen or restricted.

    风控拒绝。建议换卡重试或联系发卡行。

    SUSPECTED_RISK

    F

    The transaction cannot be further processed because of suspected security issues. You can retry the transaction after one working day. If the transaction is not secure and the user has already paid, the transaction will be refunded.

    风控拒绝。如下情况下请联系技术支持：

    • 您需要申诉。
    • 买家两周内未收到退款。

    USER_AMOUNT_EXCEED_LIMIT

    F

    The payment amount exceeds the user payment limit.

    金额超限。使用小于或等于账户可用余额的金额重新发起支付，或联系 Antom 技术支持。

    USER_BALANCE_NOT_ENOUGH

    F

    The payment cannot be completed because the user balance in the corresponding payment method is not enough.

    用户余额不足。请充值或选择其它支付方式。

    USER_KYC_NOT_QUALIFIED

    F

    The payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).

    用户先完成 KYC 认证。

    USER_PAYMENT_VERIFICATION_FAILED

    F

    The user is restricted from payment on the payment method side.

    用户未完成验证。联系技术支持了解具体原因。

    USER_STATUS_ABNORMAL

    F

    The user status is abnormal on the payment method side.

    用户状态异常。联系技术支持了解具体原因。

    PAYMENT_IN_PROCESS

    U

    The payment is being processed.

    支付处理中。

    UNKNOWN_EXCEPTION

    U

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

    未知异常。联系技术支持了解具体原因。

    CARD_NOT_SUPPORTED

    F

    The card used for the transaction is not supported.

    卡不支持。请换卡重试。

    INVALID_EXPIRATION_DATE

    F

    The value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.

    卡的有效期不正确。建议检查卡有效期是否填写及是否填写正确。

    INVALID_CARD_NUMBER

    F

    The number of the card used for the transaction is invalid.

    卡号不正确。建议换卡重试。如重试后还有问题，联系技术支持了解具体原因。

     

    支付结果事件码处理示例：
    Java
    Editor
    支付结果示例：
    支付成功
    支付失败
    Editor
    集成代码关键步骤示例

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

    Java
    Editor