Lite SDK （网络支付）

请按照本分步指南在您的应用程序中实施并启用 Yuno 的Lite Web SDK 功能。

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

确保 Yuno SDK 文件包含在网页中，然后关闭 </body> 标签。请参考下面的示例：

<script src="https://sdk-web.y.uno/v1.5/main.js"></script>

📘
支持 TypeScript
如果您使用的是 TypeScript，Yuno 提供了一个库，您可以使用该库查看 Yuno Web SDK 中的所有可用方法。

步骤 2：使用公钥Initialize SDK

在您的 JavaScript 应用程序中，创建一个 Yuno 类提供一个有效的 PUBLIC_API_KEY.检查获取应用程序接口证书指导。

像下面的例子一样，使用归属于 yuno不变。

const yuno = await YunoinitializePUBLIC_API_KEY)；

步骤 3：开始结账

您将开始结账流程。为此，请使用 yuno.startCheckout 函数，并提供必要的参数。

下表列出了所有必填参数及其说明。有关可选参数，请转至补充功能。

参数	说明
`checkoutSession`	指当前payment的结账环节.例如 `438413b7-4921-41e4-b8f3-28a5a0141638`
`elementSelector`	安装 SDK 的元素。
`countryCode`	确定正在配置payment 流程的国家。有关支持的国家及其代码，请参阅国家覆盖范围。
`language`	支付表格的语言。使用任何列出的代码。支持的语言.例如 `en-US`默认使用浏览器语言（若可用）。
`onLoading`	回调函数，用于接收payment 过程中服务器调用或加载事件的通知。
`showLoading`	控制payment 过程中 Yuno 载入/旋转器页面的可见性。默认值： `true`.
`issuersFormEnable`	启用发行人表格。默认值： `true`.
`showPaymentStatus`	显示 YunoPayment 状态页面。可在继续payment时使用。默认值： `true`.
`card.isCreditCardProcessingOnly`	可选。当 `true`确保所有银行卡交易都只作为贷记卡处理。在银行卡既可作为贷记卡又可作为借记卡的市场中非常有用。

yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "FR",
  language: "fr-FR",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  card: {
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
  onLoading: (args) => {
    console.log(args);
  },
  async yunoCreatePayment(oneTimeToken) {
    /**
     * The createPayment function calls the backend to create a payment in Yuno.
     * It uses the following endpoint https://docs.y.uno/reference/create-payment
     */
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘
交易类型
付款可以由客户（CIT）或商家（MIT）发起。有关其特点的更多信息，请参阅 "存储凭证"。
本页介绍的分步操作是指客户发起的不带重复选项的交易。通常用于一次性网上购物、店内购物、ATM 取款等。

第 4 步：安装 SDK

接下来，您必须安装 SDK，根据客户选择的付款方式进行结账。请记住，使用Lite SDK 时，您需要负责显示付款方式并捕捉客户的选择。访问Lite SDK （支付）了解更多信息。

使用 yuno.mountCheckoutLite() 功能，方法是选择一个 HTML 元素并使用有效的 CSS 选择器 (#, ., [data-*]) 显示所选payment 方式的结账。

yuno.mountCheckoutLite({
  /**
   * can be one of 'PAYPAL' | 'PIX' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Vaulted token related to payment method type.
   * Only if you already have it
   * @optional
   */
  vaultedToken: VAULTED_TOKEN,
});

安装 SDK 后，所选payment 方式流程将自动启动。

对于PayPal支付，当购物者选择PayPal后，PayPal支付页面将立即打开——无需额外确认点击。

📘
Lite SDK中的谷歌支付和 Apple 支付
Google Pay 和 Apple Pay 不能作为Lite SDK 的内置支付选项。要使用这些支付方法，您必须使用 mountExternalButtons 方法。参见安装外部按钮了解更多信息。

步骤 5：安装外部按钮（可选）

如果您想在Lite SDK 中使用 Google Pay 或 Apple Pay，您可以使用 mountExternalButtons 方法。通过这种方法，您可以选择每个按钮在用户界面中的显示位置。

// Mount external buttons
await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

"(《世界人权宣言》) mountExternalButtons 方法接受一个对象数组，每个对象包含

paymentMethodType:要么 'APPLE_PAY' 或 'GOOGLE_PAY'
elementSelector:按钮所在 HTML 元素的 CSS 选择器

卸载外部按钮

您可以卸载单个外部按钮：

yuno.unmountExternalButton('APPLE_PAY')；

或者一次性卸载所有外部按钮：

yuno.unmountAllExternalButtons()；

第 6 步：启动付款程序

用户选择payment 方式后，请记住调用 yuno.startPayment() 来启动payment 流程。下面是一个示例 yuno.startPayment() 当用户点击 button-pay:

const PayButton = document.querySelector("#button-pay");

PayButton.addEventListener("click", () => {
  yuno.startPayment();
});

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

一旦客户在 Yuno 的支付表单中填写了所需数据，SDK 就会提供一次性token。配置功能 yunoCreatePayment(oneTimeToken) 然后用一次性token触发。

yunoCreatePaymentoneTimeToken)；

您还可以使用 tokenWithInformation 以接收客户在结账时提供的任何附加信息，如分期付款或文件类型/编号。

yunoCreatePaymentoneTimeToken, tokenWithInformation)；

📘
装载机管理
商家负责管理加载器。Yuno 提供了一个默认加载器选项，但商家也可以根据自己的喜好实施自己的加载器。在这种情况下，商家应负责进行必要的配置。

步骤 8：创建付款

完成上述步骤后，就可以创建付款。必须使用 "创建付款"（Create Payment） endpoint来创建背对背付款。商家应调用自己的后台，使用一次性token 和结账会话在 Yuno 中创建付款。

📘
继续Payment 方式
Yuno 建议将 continuePayment 方法。这是因为某些异步payment 方法需要客户执行额外操作才能完成payment。API 会通过 sdk_action_required 字段，该字段将返回为 true。返回 yuno.continuePayment() 功能将向客户显示附加屏幕，客户可在屏幕上执行必要操作以完成payment。如果 sdk_action_required 为假，则无需执行此步骤。

补充功能

Yuno Web SDK 提供额外的服务和配置，可用于改善客户体验：

安装外部按钮

使用 mountExternalButtons 方法在自定义用户界面中呈现 Google Pay 和 Apple Pay 按钮。如果想在Lite SDK 中使用这些支付方法，就必须使用该方法，因为它们不是内置的支付选项。

await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

参数

参数	说明
`paymentMethodType`	付款方式类型。必须是 `'APPLE_PAY'` 或 `'GOOGLE_PAY'`.
`elementSelector`	按钮所在 HTML 元素的 CSS 选择器（例如 `'#apple-pay'`, `'.button'`).

卸载按钮

您可以按付款方式类型卸载单个外部按钮：

yuno.unmountExternalButton('APPLE_PAY')；

或者一次性卸载所有外部按钮：

yuno.unmountAllExternalButtons()；

装载机

控制装载机的使用。

参数	说明
`showLoading`	您可以隐藏或显示 Yuno 载入/旋转器页面。启用此选项可确保加载组件一直显示，直到 `hideLoader()` 或 `continuePayment()` 函数被调用。默认值为 true。

yuno.startCheckout({
  showLoading: true,
});

发行人的形式

参数	说明
`issuersFormEnable`	通过该参数，您可以配置 SDK 以启用签发人表格（银行列表）。

yuno.startCheckout({
  issuersFormEnable: true,
});

表格渲染模式

📘
Lite SDK v2.0 中的增强渲染模式
增强型Lite SDK v2.0 提供高级呈现模式功能，可将 Yuno 的结账表单直接嵌入您的界面。这样，您就可以完全控制结账流程，包括加载、状态和付款输入屏幕，并实现完全可视化定制和无缝用户体验集成。

参数	说明
`renderMode`	该可选参数决定payment 表单的显示方式。
	`type`:要么 `'modal'` 或 `'element'`.
	`elementSelector`:如果 `type` 是 `'element'`.指定渲染表格的位置。
`elementSelector`	当 `type` 是 `'element'`.指定挂载 Yuno SDK 的位置。
	字符串（已废弃）：安装 SDK 的 ID 或选择器。
	对象：指定 APM 和操作表单的元素：
	`apmForm`:显示 APM 的元素。
	`actionForm`:的元素继续付款按钮，该按钮会打开一个模态，用于完成医疗服务提供者特定的付款步骤。

yuno.startCheckout({
  renderMode:

卡片形式配置

参数	说明
`card`	配置信用卡表单的设置：
	`type`卡片表单布局类型。选项： `step` 或 `extends`
	`styles`编写自定义CSS来设置卡片表单样式。您的CSS将被注入到iframe中。
	`cardSaveEnable`显示复选框以保存或注册卡片。默认值为 `false`.
	`texts`卡片表单按钮的自定义文本。
	`cardNumberPlaceholder`可选。卡号字段的自定义占位符文本。支持字母数字字符、空格及本地化所需的UTF-8字符。若未提供，SDK将使用默认英文占位符（"Card number"）。此自定义设置不影响卡片格式、遮罩处理、BIN逻辑或验证功能。
	`hideCardholderName`可选。当设置为 `true`在卡片表单中，持卡人姓名字段被隐藏。当未指定或设置为 `false`持卡人姓名字段将显示（默认行为）。隐藏该字段不会影响主卡号、有效期、CVV收集、BIN逻辑或3DS/服务商验证。
	`onChange`回调函数在卡片信息状态发生变化时触发。当发生与卡片相关的事件时调用，例如在数据获取（加载）期间、完成后、选择网络（如Visa、Mastercard）时，或卡片表单重置时。接收 `{error, data}` 其中 `data` 包含卡片IIN（发卡机构识别码，亦称BIN——银行识别码）信息及分期付款选项。BIN（卡号前6位数字）可用于实时税费计算。其功能与安全字段相同。 `options.onChange` 方法。

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    cardSaveEnable: false,
    texts: {},
    cardNumberPlaceholder: "Enter card number", // Optional: Custom placeholder text
    hideCardholderName: false, // Optional: Set to true to hide cardholder name field
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
});

为未来付款保存银行卡

此外，您还可以显示一个复选框，以便使用 cardSaveEnable: true.以下是两种卡片表单复选框的示例。

渲染模式

下面的截图展示了以下不同之处：

渲染模式 modal 和 elements payment 方式列表
渲染模式 step 和 extends 信用卡表格

您还可以为贺卡表单选择其中一个渲染选项、 step 和 extends:

文本payment 表格按钮

参数	说明
`texts`	为支付表单按钮提供自定义文本，以匹配您应用程序的语言或品牌。

yuno.startCheckout({
  texts: {
    customerForm?: {
      submitButton?: string;
    }
    paymentOtp?: {
      sendOtpButton?: string;
    }
  }
})

持续填写信用卡表单以重试付款

如果交易被拒绝，您可以使用信用卡表单，在客户输入信用卡详细信息后重新尝试payment 。为此，您需要

在初始化 SDK 时添加以下参数，以便在创建一次性使用token 后持久化信用卡表单：
```
yuno.startCheckout({
  automaticallyUnmount: false,
});
```
如果交易被拒绝，您需要
1. 执行方法 yuno.notifyError() 删除之前为第一笔交易输入的 CVV。
2. 创建一个新的结账会话，并执行以下操作，用新的会话更新 SDK yuno.updateCheckoutSession(checkoutsession)
继续使用新的结账和一次性使用token 以及常规支付流程。

隐藏支付按钮

您可以隐藏薪酬按钮。要控制这一功能，您需要设置 showPayButton 至 false 在使用 startCheckout 功能。下面的代码块举例说明了如何隐藏payment 按钮：

yuno.startCheckout({
  /**
   * Hide (false) or show (true) the customer or card form pay button
   * @default true
   * @optional
   */
  showPayButton: false,
});

下面的图片展示了客户数据表格中带有和不带支付按钮的示例：

下面的图片展示了带支付按钮和不带支付按钮的卡片表单示例：

如果您将薪酬按钮，您需要通过代码开始创建一次性token 。要创建一次性token 并在后台继续付款，请调用 submitOneTimeTokenForm 功能。下面的代码块介绍了如何使用 submitOneTimeTokenForm 功能。

/**
 * 该函数触发的功能与客户点击支付表单按钮时调用的功能相同。如果您选择了步进渲染模式，则此方法不起作用。
 */
yuno.submitOneTimeTokenForm()；

保持更新

请访问更新日志，了解最新的 SDK 更新和版本历史。