Seamless SDK （支付 Android）

本页面为您提供有关用于安卓支付的 YunoSeamless SDK 的指南。

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

该 SDK 是以下商家的理想选择：

希望在利用预置用户界面组件的同时控制支付流程
需要定制支付体验，同时保持 PCI 合规性
要求在实施速度和定制之间取得平衡

Seamless SDK 包括以下功能：

预置支付 UI 组件，提供定制选项
支持多种付款方式
高级付款状态处理
全面的错误管理

如果商家需要完整的用户界面控制或更高级的功能，可考虑使用我们的 Full SDK来代替。

要求

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

您必须拥有一个激活的 Yuno 账户。
您需要 Yuno API 凭据 (account_id, public-api-key和 private-secret-key)，您可以从 Yuno 仪表板的开发人员部分.向 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 集成步骤 6 中使用的 ID

💳
通过发送控制认证与捕获 payment_method.detail.card.capture 在结账环节： false = 仅授权， true = 立即捕获。

关键参数

参数	需要	说明
`amount`	是	主交易金额对象包含 `currency` (ISO 4217 代码）和 `value` (该货币的数字金额）。
`alternative_amount`	没有	交易金额的另一种货币表示形式，其结构与 `amount` (`currency` 和 `value`).适用于多币种场景，例如以客户偏好的货币（如美元）显示价格，同时以当地货币（如 COP）处理付款。

🚧
结账会话使用情况
"(《世界人权宣言》) checkout_session 对每次付款尝试来说都是唯一的，不能重复使用。

第 3 步：将 SDK 添加到项目中

添加版本库源：

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

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

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

步骤 4：配置权限

Yuno SDK 需要网络权限。确保 INTERNET 权限包含在您的 AndroidManifest.xml:

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

步骤 5：Initialize SDK

从Yuno 面板读取公共 API 密钥。

如果还没有实施自定义应用程序，请创建一个。在 onCreate() 方法，调用initialize 函数 (Yuno.initialize):

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

使用 YunoConfig 数据类，为 SDK 设置其他配置。下表列出并描述了自定义选项：

选项	说明
卡片流	定义卡片表格流程。默认选项为 `CardFormType.ONE_STEP`.检查章节渲染选项了解更多信息。
SaveCardEnabled	启用卡片流的保存卡片复选框。更多信息请查看保存卡片部分。
语言	定义付款表单中使用的语言。您可以将其设置为可用语言选项之一： es (西班牙文) en (英语) pt (葡萄牙语) 菲力 id（印尼语）马来文 th（泰语） zh-TW（繁体中文，台湾 zh-CN （简体中文，中国 vi（越南语）法文 pl (波兰语) it（意大利语）德文 ru（俄文） tr (土耳其语) nl（荷兰语） sv（瑞典语）韩语 ja (日语)
款式	支持 SDK 范围内的用户界面自定义。使用它可以定义全局可视化样式，如字体家族和按钮外观（颜色、填充、半径、排版）。 `YunoStyles` 对象。更多信息，请查看 `styles` 节。
卡号占位符	此可选字段允许您自定义卡号字段的占位符文本。支持字母数字字符、空格及用于本地化的UTF-8字符。若未提供，SDK将使用默认占位符（"卡号"）。此自定义操作不会影响卡片格式、遮罩处理、BIN逻辑或验证功能。
隐藏持卡人姓名	此可选字段允许您在卡片表单中隐藏持卡人姓名字段。当设置为 `true`持卡人姓名字段未显示。当未指定或设置为 `false`持卡人姓名字段将显示（默认行为）。隐藏该字段不会影响主卡号、有效期、CVV验证码收集、BIN逻辑或3DS/支付机构验证。当支付机构要求提供持卡人姓名时，商户有责任确保该信息被提交。

下面的代码块显示了 YunoConfig:

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

步骤 6：开始结账

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

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

参数	说明
`checkoutSession`	"(《世界人权宣言》) `checkout_session` 与付款有关。
`country_code`	执行付款的国家代码。有关支持国家及其代码的完整列表，请参阅国家覆盖范围。
`callbackPaymentState`	返回当前付款流程的函数。如果不需要结果，则可选。
`merchantSessionId`	商家会话跟踪的可选标识符。默认为空。

下列表格返回的可能付款状态 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" (取消)

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

国家	说明	需要采取的额外行动
`SUCCEEDED`	交易或付款过程成功完成，无任何错误。	不
`FAIL`	由于数据验证问题、服务器连接故障或技术/网络问题等错误导致交易失败。	调查故障原因（验证、网络、服务器）并采取纠正措施。
`PROCESSING`	交易正在进行中，等待批准或核实。	不
`REJECT`	由于资金不足或涉嫌欺诈活动等原因，交易被拒绝。	是的，告知用户被拒绝的原因，如果可能的话提供理由，并建议采取的行动。
`INTERNAL_ERROR`	处理付款过程的系统出现意外内部错误。	是。需要技术干预，以审查系统、修复内部问题、重试或通知用户。
`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 始终如一地

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

第 7 步：获取一次性支付token (OTT)

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

startPaymentSeamlessLite(
   paymentSelected： PaymentSelected,
   callbackPaymentState: ((String?) -> Unit)?
   showPaymentStatus：Boolean、
)

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

参数	说明
`paymentSelected`	指定支付方式，可以是金库token ，也可以是选定的支付类型。
`callbackPaymentState`	这是一个可选参数。该函数处理状态更新。
`showPaymentStatus`	这是一个可选参数。当 `true`，显示 SDK 的默认结果屏幕。

您将通过以下方式收到付款状态 callbackPaymentState会显示付款是否成功或是否出现问题。

步骤 8：创建付款

调用方法 startPaymentSeamlessLite 使用所选付款方式完成付款流程：

startPaymentSeamlessLite(
   paymentSelected： PaymentSelected,
   callbackPaymentState: ((String?) -> Unit)?
   showPaymentStatus：Boolean、
)

补充功能

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

`styles`

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

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

参数	说明
`buttonStyles`	自定义 SDK 中显示的主要按钮。
`fontFamily`	设置所有 SDK 文本元素使用的字体系列。

"(《世界人权宣言》) 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 数据类（如步骤 5 所述），以使用 styles 自定义选项。

装载机

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

为未来付款保存银行卡

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

渲染选项

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

📘
访问演示应用程序
除了提供的代码示例，您还可以查看Yuno 存储库，以完成 Yuno Android SDK 的实施。