Lite SDK (Payment Android)

👍

推荐的 SDK

我们建议使用AndroidSeamless SDK，以获得流畅的集成体验。该选项提供了灵活的支付解决方案，预置了用户界面组件和定制选项。

本页面为您提供安卓支付的 YunoLite SDK 指南。该 SDK 简化了集成流程，提供了基本的支付功能，非常适合有以下需求的商家：

• 需要快速实施，并将定制要求降至最低
• 希望主要专注于银行卡支付处理
• 首选可处理付款流程的即用型用户界面

Lite SDK 包括以下核心功能：

• 预置支付 UI 组件
• 银行卡支付处理
• 基本付款状态处理
• 基本错误管理

对于需要多种支付方式、自定义用户界面或高级防欺诈等更高级功能的商户，请考虑使用我们的 Full SDK来代替。

要求

在开始 Yuno Android SDK 集成之前，请确保您的项目符合技术要求。此外，还要确保具备以下先决条件：

• 您必须拥有一个激活的 Yuno 账户。
• 您需要 Yuno API 凭据 (account_id, public-api-key和 private-secret-key)，您可以从 开发人员证书部分 的证书。要验证对 Yuno API 的请求，需要这些凭证。API 用于
  • 创建一个 customer在开始付款之前需要
  • 创建一个 checkout_session初始化付款流
  • 创建与会话相关的付款

📘

SDK 版本

请参阅发布说明或Yuno Android SDK 存储库，以验证当前可用的 SDK 版本。

步骤 1：创建客户

在开始付款前，使用创建客户endpoint创建客户。需要此步骤来

• 确定付款人的身份
• 启用存储卡功能（如果已启用）
• 跟踪付款历史

从该endpoint 返回的客户 ID 将用于创建 checkout_session.

步骤 2：创建结账会话

创建一个新的 checkout_session 使用 创建结账会话 endpoint 来initialize 支付流程。确保

• 包括上一步获得的客户 ID
• 存储返回的 checkout_session 集成步骤 5 中使用的 ID
• "(《世界人权宣言》) checkout_session 每次付款都是唯一的，不能重复使用

🚧

外部浏览器返回处理

如果您的支付流程将用户发送到外部浏览器（例如，用于 3DS 身份验证或银行重定向），请确保设置 callback_url 创建结账会话时使用。有关处理返回应用程序的分步指南，请参阅 处理外部浏览器返回 (callback_url).

第 3 步：在项目中加入程序库

通过 Gradle 在项目中包含 Yuno SDK 文件。添加版本库源代码：

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

在 build.gradle 文件，将 Yuno SDK 依赖关系添加到应用程序中：

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

权限

Yuno SDK 包括 INTERNET 默认情况下，该权限是提出网络请求所必需的。

<uses-permission android:name="android.permission.INTERNET" />

步骤 4：使用公钥Initialize SDK

Initialize SDK：

1. 从Yuno 面板获取公共 API 密钥
2. 如果没有，创建自定义应用程序类
3. 通过调用 Yuno.initialize() 中的 onCreate() 方法，传递您的 API 密钥和配置：

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config: YunoConfig,
    )
  }
}

使用数据类 YunoConfig 来定制 SDK 的行为。在调用 Yuno.initialize().可用的选项有

data classYunoConfig(
    val cardFlow:CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val cardFormDeployed: Boolean = false,
    val language:YunoLanguage? = null,
    val styles:YunoStyles? = null,
    val cardNumberPlaceholder: String? = null, // 可选：卡号字段的自定义占位文本
    val hideCardholderName: Boolean? = null // 可选：设为true隐藏持卡人姓名字段
)

下表介绍了每个自定义选项：

您还需要更新您的清单，以便使用您的应用程序：

<application android:name=".CustomApplication"></application>

步骤 5：开始结账

致电 startCheckout 方法中的 onCreate() 活动的功能，该功能集成了 SDK，可使用Lite SDK 启动新的支付流程：

startCheckout(
 checkoutSession："checkout_session"、
 countryCode："US"、
 callbackPaymentState: ((String?) -> Unit)?
  merchantSessionId：String? = null
)

下表描述了启动结账所需的参数：

回拨付款状态

"(《世界人权宣言》) callbackPaymentState 参数是一个返回当前付款流程的函数。如果不需要结果，则不必发送此函数。以下代码块显示了可能的状态：

const valSUCCEEDED=SUCCEEDED"
const val PAYMENT_STATE_FAIL = "FAIL" (失败)
const val PAYMENT_STATE_PROCESSING = "PROCESSING" (处理中)
const val PAYMENT_STATE_REJECT = "REJECT" (拒绝)
const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR" (内部错误)
const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED" (取消)

下表提供了有关可能状态的更多信息：

付款状态验证

本节说明当用户取消或退出支付流程时，SDK如何处理支付状态，以及在这些场景中SDK状态与后端支付状态之间的关联关系。

同步支付方式（Google Pay）

对于Google Pay等同步支付方式，当用户在收到支付服务提供商（PSP）响应前取消或关闭钱包界面时：

• SDK状态: 返回 CANCELED (CANCELLED)
• 后端支付状态：遗骸 PENDING 直至PSP超时或商户取消
• 重要SDK 将不返回 REJECT 或 PROCESSING 在此情境下

这确保后端支付保持待处理状态，并能由商户系统妥善处理。

异步支付方式（PIX及基于二维码的支付方式）

对于PIX等异步支付方式，当用户在完成支付前关闭二维码窗口（点击X）时：

• SDK状态: 返回 PROCESSING，可选地带有子状态，例如 CLOSED_BY_USER
• 后端支付状态：遗骸 PENDING 且二维码在到期前始终有效
• 结账会话复用：重新打开相同的结账会话可显示相同的有效二维码
• 不自动取消：当用户关闭二维码窗口时，PIX支付不会自动取消

此功能允许用户在二维码失效前返回支付流程，使用同一二维码完成交易。

已过期的异步支付

如果PIX二维码自然过期：

• 后端状态更新至 EXPIRED
• SDK状态SDK 回调和轮询endpoints 点返回 EXPIRED 始终如一地

这确保了当支付方式过期时，商户能够收到准确的状态信息。

第 6 步：启动付款程序

调用方法 startPaymentLite 以启动付款程序：

startPaymentLite(
   paymentSelected： PaymentSelected,
   callbackOTT:(String?) -> Unit、
   callBackTokenWithInformation:OneTimeTokenModel?) -> Unit、
   showPaymentStatus：Boolean、
)

下表描述了启动支付所需的参数：

发送一个附加参数，即保险库token 和/或用户选择的支付类型：

PaymentSelected(
 vaultedToken : 字符串 "payment_vaulted_token"、
 paymentMethodType  ：字符串 "payment_type"、
)

第 7 步：获取 OTT（一次性token

一次性token 是代表支付会话的唯一标识符。创建支付时需要使用此token 。

回调一次性token

一次性token 回调会返回以下参数：

🚧

装载机操作

商家负责处理加载器。Yuno 提供使用我们的加载器的选项；但是，商家可以使用自己的加载器，并且必须进行相应的配置。

步骤 8：创建付款

完成前面的步骤后，从后台调用创建付款 endpoint来创建付款。该endpoint 需要

• 在步骤 7 中获得的一次性token
• "(《世界人权宣言》) checkout_session 在步骤 2 中获得

🚧

继续整合付款方式

Yuno 需要 您将整合 continuePayment 因为某些异步支付方法需要客户执行额外操作才能完成。API 会通过 sdk_action_required 字段，该字段将返回为 true。返回 yuno.continuePayment() 该功能将向客户显示额外的屏幕，客户可以在屏幕上执行必要的操作来完成支付，而无需您处理每一种情况。

对于需要额外客户操作（如 3DS 身份验证挑战）或异步处理（如银行转账）的支付方法，您需要集成 SDK 的 continuePayment 方法创建付款。创建付款 API 响应包括一个 sdk_action_required 字段，表示是否需要这一步骤：

• 如果 TRUE:致电 yuno.continuePayment() 显示客户操作的附加屏幕（如 3DS 验证、银行重定向页面）
• 如果 FALSE:跳过此步骤，因为不需要与客户进行额外的互动

下面的代码块展示了如何执行付款延续流程：

continuePayment(
   showPaymentStatus：Boolean = true、
   checkoutSession：= null、
   countryCode：String?
   callbackPaymentState: ((String?) -> Unit)? = null
)

发送 FALSE 在 showPaymentStatus 参数来显示付款状态屏幕。然后，通过回调获取付款状态。

渲染模式（高级集成）

对于需要高级用户界面控制的开发人员，Lite SDK 还支持呈现模式集成。该模式提供基于片段的用户界面组件，您可以将其集成到自定义布局中，从而在保持精简版Lite SDK 功能的同时提供更多灵活性。

基本渲染模式设置

使用 startPaymentRender 进行高级用户界面集成：

fun Activity.startPaymentRender(
   checkoutSession：= null、
   countryCode：= null、
    coroutineScope：CoroutineScope、
   paymentSelected： PaymentSelected,
    listener：YunoPaymentRenderListener、
):YunoPaymentFragmentController

实施示例

class PaymentActivity : Activity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    private fun initializeRenderMode() {
        fragmentController = startPaymentRender(
            checkoutSession = checkoutSessionId,
            countryCode = "US",
            coroutineScope = lifecycleScope,
            paymentSelected = PaymentSelected.CARD,
            listener = object : YunoPaymentRenderListener {
                override fun showView(fragment: Fragment) {
                    supportFragmentManager.beginTransaction()
                        .replace(R.id.payment_container, fragment)
                        .commit()
                }

                override fun returnOneTimeToken(oneTimeToken: String, additionalData: OneTimeTokenModel?) {
                    processPayment(oneTimeToken) {
                        fragmentController.continuePayment()
                    }
                }

                override fun returnStatus(resultCode: Int, paymentStatus: String) {
                    handlePaymentResult(paymentStatus)
                }

                override fun loadingListener(isLoading: Boolean) {
                    updateLoadingUI(isLoading)
                }
            }
        )
    }
}

主要优势

• 自定义 UI 集成：在现有布局中嵌入支付组件
• 片段兼容性：兼容 XML 和 Jetpack Compose
• 流程控制：手动管理表单提交和继续付款

🚧

高级功能

渲染模式专为需要自定义用户界面集成的开发人员设计。对于更简单的实现，请使用前面步骤中描述的标准Lite SDK 方法。

补充功能

Yuno Android SDK 提供额外的服务和配置，您可以用来改善客户体验。使用SDK 定制功能可更改 SDK 外观，使其与您的品牌相匹配，或配置加载器。

styles

随着 styles 自定义选项，您可以通过一个 YunoStyles 对象。通过自定义按钮外观和排版，您可以在整个 SDK 中应用一致的品牌。

data classYunoStyles(
    val buttonStyles：YunoButtonStyles? = null、
    val fontFamily：= null
)

"(《世界人权宣言》) YunoButtonStyles 对象可让您定义按钮外观的特定设置：

data class YunoButtonStyles(
    val backgroundColor: Color? = null、
    val contentColor: Color? = null、
    val cornerRadius：= null
    val elevation：= null、
    val padding：= null、
    val fontFamily：= null、
    val fontSize：TextUnit? = null、
    val fontStyle：FontStyle?
)

使用 YunoConfig 数据类，以使用步骤 4 中描述的 styles 自定义选项。

装载机

通过 keepLoader 参数中的 YunoConfig 数据类，该类已在上文 SDK 配置部分内嵌记录。

为未来付款保存银行卡

您还可以显示一个复选框，以便使用 cardSaveEnable: true.以下示例显示了两种卡片表单渲染的复选框：

渲染选项

您可以选择两种卡片表单渲染选项。下面的截图显示了 cardFormType ONE_STEP 和 STEP_BY_STEP:

SDK 定制

您可以更改 SDK 的外观，使其与您的品牌相匹配。有关详细信息，请参阅SDK 定制页面。

📘

演示应用程序

除了提供的代码示例，您还可以查看Yuno 存储库，以完成 Yuno Android SDK 的实施。