Full SDK （网络）实施

本页提供了在应用程序中实施和启用 YunoFull Web SDK 功能的分步指南。

📘
更新日志参考：
本指南涵盖当前的 SDK 版本。有关以前版本的详细信息，请参阅更新日志。

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

在 HTML 文件中添加以下脚本标记，以包含 Yuno Web SDK：

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

您也可以通过 npm 安装：

npm install @yuno-payments/sdk-web

完成 SDK 集成后，请执行以下步骤以实现完整的结账功能。

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

步骤 2：使用公钥Initialize SDK

创建一个 Yuno 类提供一个有效的 PUBLIC_API_KEY.参见凭证页面获取更多信息。

使用公共 API 密钥Initialize SDK：

const yuno = await YunoinitializePUBLIC_API_KEY)；

步骤 3：开始结账

使用 yuno.startCheckout 函数，使用必要的参数启动结账流程。

参见参数表如下的所有选项。 startCheckout.

有关进一步的自定义或高级/可选设置，请参阅补充功能部分。

参数

下表列出了以下功能的所有可用参数 startCheckout 方法，并附有说明：

参数	说明
`checkoutSession`	指当前payment的结账环节.例如 `'438413b7-4921-41e4-b8f3-28a5a0141638'`
`elementSelector`	安装 SDK 的元素。
`countryCode`	该参数用于指定正在设置payment 流程的国家。使用 `ENUM` 值代表所需的国家代码。支持的国家及其相应代码的完整列表可在覆盖国家 page.
`language`	支付表格的语言。使用任何列出的代码。支持的语言.例如 `en-US`默认使用浏览器语言（若可用）。
`onLoading`	在payment 过程中接收服务器调用或加载事件的通知时需要使用。
`showLoading`	控制payment 过程中 Yuno 载入/旋转器页面的可见性。默认情况下 `true`.
`issuersFormEnable`	启用发行人表格。默认为 `true`.
`showPaymentStatus`	显示 YunoPayment 状态页面。继续payment 时也可以使用此选项。默认为 `true`.
`card.isCreditCardProcessingOnly`	此功能可确保所有卡交易均以纯信用卡方式处理。该选项在巴西等市场尤为实用，因当地卡片可兼具信用卡与借记卡功能。启用时，请设置 `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);
  },
  yunoPaymentMethodSelected: () => {
    console.log("Payment method selected");
  },
  yunoPaymentResult: (status) => {
    console.log("Payment result:", status);
  },
  yunoError: (message, data) => {
    console.error("Payment error:", message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘
渲染模式
默认情况下，Yuno SDK 会渲染为模态。不过，您可以指定 SDK 渲染的元素。有关更多信息，请访问补充功能页面下的渲染模式。

📘
onPaymentMethodSelected 活动
适用于所有 APM，包括 Google Pay、Apple Pay 和 PayPal、 onPaymentMethodSelected 会在客户选择payment 方式后立即触发（在payment 流程开始前）。定义 onPaymentMethodSelected 于 startCheckout 之前 mountCheckout.

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

📘
谷歌支付和 Apple 支付显示屏
从 SDK 1.5 版开始，Google Pay 和 Apple Pay 在支付方式列表中显示为直接按钮，而不是单选按钮。它们与其他支付方式分开显示。

第 4 步：安装 SDK

显示付款方式：

yunomountCheckout()；

安装时已选择默认付款方式：

yuno.mountCheckout({
  paymentMethodType: PAYMENT_METHOD_TYPE,
  vaultedToken: VAULTED_TOKEN,
});

步骤 5：启动payment 程序

致电 yuno.startPayment() 以在用户选择付款方式后启动付款流程：

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

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

步骤 6：获取 OTT（一次性token

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

yunoCreatePaymentoneTimeToken)；

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

yunoCreatePaymentoneTimeToken, tokenWithInformation)；

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

第 7 步：创建付款

完成前面的步骤后，继续创建付款。必须使用 "创建付款"（Create Payment） endpoint来创建背对背付款。商家的后台应调用该endpoint ，使用一次性token 和结账会话在 Yuno 中创建付款。

📘
完成整合
完成步骤 7 后，您就成功实施了基本支付流程。要测试集成，请使用结账会话和一次性token创建一个测试付款。有关其他功能和高级配置，请参阅下面的补充功能部分。

❗️
继续付款方法
创建payment后，Yuno 需要您可以将 continuePayment 方法。这是必要的，因为某些异步payment 方法需要额外的客户操作才能完成流程。API 响应将通过设置 sdk_action_required 字段为 true。出现这种情况时，必须调用 yuno.continuePayment()它将自动向客户显示必要的屏幕，使他们能够完成payment 流程，而无需您手动处理每个案例。

`continuePayment` 返回值或空

对于需要商户端操作的payment 方法（例如，当payment 提供商要求在网络视图中重定向 URL 时），"... await yuno.continuePayment() 方法要么返回一个具有以下结构的对象，要么返回 null：

{
  action: 'REDIRECT_URL'
  type: string
  redirect: {
    init_url: string
    success_url: string
    error_url: string
  }
} | null

当该方法返回一个对象时，您可以处理应用程序中需要自定义重定向处理的支付流程。如果返回空值，则不需要额外的商户端操作。

📘
演示应用程序
除提供的代码示例外，您还可以访问演示应用程序，了解 Yuno SDK 的完整实现。演示应用程序包含所有 Yuno SDK 的工作示例，可从GitHub 存储库中克隆。

补充功能

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

安装外部按钮
表格装载机
渲染模式
卡片形式配置

安装外部按钮

您可以使用 mountExternalButtons 方法，在用户界面的自定义位置显示 Google Pay 和 Apple Pay 按钮。这样您就可以控制这些按钮的显示位置。

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,
});

渲染模式

参数	说明
`renderMode`	这个可选参数决定了付款表格的显示模式。
	`type`可以是 `modal` 或 `element`.
	`elementSelector`:渲染表单的元素。只有在 `type` 是 `element`.
`elementSelector`	仅在类型为 `element`.指定要挂载 Yuno SDK 的 HTML 元素。您可以使用以下选项之一指定元素：
	字符串（已废弃）：提供安装 SDK 的元素的 ID 或选择器。
	对象:指定安装 APM 和操作表单的元素。您需要为 `apmForm`显示 APM 的元素，以及 `actionForm`继续付款按钮出现在此处。点击该按钮将弹出模态窗口，显示通过支付服务商完成付款的步骤。

yuno.startCheckout({
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

卡片形式配置

参数	说明
`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;
    }
  }
})

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

如果交易被拒绝，您可以使用信用卡表单，在客户输入信用卡详细信息后重试付款。具体操作如下

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

隐藏支付按钮

在显示卡片或客户资料表单时，可以隐藏支付按钮。设置 showPayButton 至 false 在使用 startCheckout 功能：

yuno.startCheckout({
  showPayButton: false,
});

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

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

如果您隐藏了支付按钮，则需要通过代码开始创建一次性token 。要创建一次性token 并在后台继续付款，请调用 submitOneTimeTokenForm 功能：

yuno.submitOneTimeTokenForm()；

可选的初始化 `options` 规范

该可选功能适用于需要自定义如何通过 cookie 处理设备识别的高级用例。

从 Yuno SDK v1.2 开始，"... Yuno.initialize 函数支持一个名为 options.这样就可以进行高级配置，例如自定义用于设备识别的 cookie 名称。

初始化选项

更新后的函数签名为

const yuno = await Yunoinitialize(publicApiKey, applicationSession, options)；

publicApiKey (string):您的公共 API 密钥。
applicationSession (string | undefined):可选的会话 ID。

建议将其保留为 undefined 这样 SDK 就能在内部生成并管理自己的会话。只有在需要自定义会话管理策略时才设置此项。
options (object | undefined):用于高级配置的可选对象。

期权结构

"(《世界人权宣言》) options 对象支持以下结构：

const options = {
  cookies: {
    deviceId: {
      name: "customCookieName",
    },
  },
};

如果 deviceId.name 未指定时，SDK 默认使用 "yuno" 作为 cookie 名称。

实施示例

const publicApiKey = "your-public-api-key";
const options = {
  cookies: {
    deviceId: {
      name: "custom-device-id",
    },
  },
};

const yuno = await Yuno.initialize(publicApiKey, undefined, options);

下一步是什么？

访问补充功能，了解Full SDK 的其他配置。您还可以访问 Yuno Web SDK 提供的其他功能：

SDK 定制：更改 SDK 外观，使其与您的品牌相匹配
Payment 状态：向用户更新payment 流程
3DS 设置 SDK：将 3DS 整合到您的payment 流程中

随时掌握最新动态

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

更新日志参考：

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

TypeScript 库

步骤 2：使用公钥Initialize SDK

步骤 3：开始结账

参数

渲染模式

onPaymentMethodSelected 活动

谷歌支付和 Apple 支付显示屏

第 4 步：安装 SDK

步骤 5：启动payment 程序

步骤 6：获取 OTT（一次性token

装载机管理

第 7 步：创建付款

完成整合

继续付款方法

continuePayment 返回值或空

演示应用程序

补充功能

安装外部按钮

参数

卸载按钮

表格装载机

发行人表格

渲染模式

卡片形式配置

为未来付款保存银行卡

渲染模式

文本payment 表格按钮

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

隐藏支付按钮

可选的初始化 options 规范

初始化选项

期权结构

实施示例

下一步是什么？

随时掌握最新动态

`onPaymentMethodSelected` 活动

`continuePayment` 返回值或空

可选的初始化 `options` 规范