Lite SDK (网络注册)

👍

推荐的 SDK

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

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

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

在继续实施Lite SDK 之前,请参阅SDK 集成概述,了解如何将 SDK 正确集成到项目中的详细说明。

集成指南提供了三种灵活的方法:

  • 方法 1 (HTML):在 HTML 文件中添加一个脚本标签。这是最简单的方法,适用于基本实现和快速原型
  • 方法 2(动态 JavaScript):通过自定义错误处理和加载状态,以编程方式加载 SDK。最适合需要对集成进行更多控制的应用程序
  • 方法 3(国家预防机制):在现代 JavaScript 应用程序中使用我们的 NPM 软件包。这是我们推荐的方法,具有依赖管理、树状结构和 TypeScript 支持功能

1.在 HTML 中直接添加 SDK 脚本

集成 Yuno SDK 的最简单方法是添加一个 <script> 标签到 HTML 文件中。这种方法既能快速实现,又能保持适当的异步加载。SDK 公开了一个事件,在完全加载时发出通知,确保您能在正确的时间安全地initialize 并使用其功能。

首先,设置事件监听器,然后加载 SDK:

<script>
  window.addEventListener('yuno-sdk-ready', () => {
    console.log('SDK loaded');
    const yuno = await Yuno.initialize(PUBLIC_API_KEY);
  });
</script>

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

2.使用 JavaScript 动态注入 SDK

动态 JavaScript 注入方法增强了对 SDK 加载和初始化的控制。通过这种方法,您可以

  • 在需要时以编程方式加载 SDK
  • 实施自定义加载状态和错误处理
  • 精确控制 SDK 的可用时间
  • 将 SDK 初始化与应用程序逻辑同步
  • 为您的使用案例量身定制错误处理方法

当您需要对 SDK 的加载过程进行细粒度控制,并希望精确处理各种情况时,这种方法非常理想。

创建一个动态注入 SDK 的函数:

export const injectScript = async (): Promise<boolean> => {
  const head = document.getElementsByTagName('head')[0];
  const js = document.createElement('script');
  js.src = "https://sdk-web.y.uno/v1.5/main.js";
  js.defer = true;

  return new Promise((resolve, reject) => {
    window.addEventListener('yuno-sdk-ready', () => {
      resolve(true);
    });

    js.onerror = (error) => {
      const event = new CustomEvent('yuno-sdk-error', { detail: error });
      window.dispatchEvent(event);
      reject(new Error(`Failed to load script: ${js.src} - ${error.message}`));
    };

    head.appendChild(js);
  });
};

使用该函数注入 SDK:

await injectScript();
const yuno = await YunoinitializePUBLIC_API_KEY);

3.使用 NPM 模块

对于使用 NPM 软件包管理的项目,您可以通过 NPM 将 SDK 作为模块安装。这种方法提供了更好的依赖关系管理、版本控制以及与现代 JavaScript 构建工具和框架的无缝集成。这对使用 webpack、Rollup 或 Vite 等捆绑程序的应用程序尤其有利。

npm install @yuno-payments/sdk-web

然后,按如下步骤加载并initialize SDK:

import { loadScript } from '@yuno-payments/sdk-web';

await loadScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

选择最适合您的开发工作流程和技术要求的集成方法。完成 SDK 集成后,您可以继续执行以下步骤来实现简版注册功能。

📘

TypeScript 库

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

步骤 2:使用公钥Initialize SDK

在您的 JavaScript 应用程序中,创建一个 Yuno 类提供一个有效的 PUBLIC_API_KEY.检查 获取应用程序接口证书 如果您没有证书,请使用本指南。在下面的示例中,初始化的类归属于 yuno不变。

const yuno = await YunoinitializePUBLIC_API_KEY);

步骤 3:创建客户会话和注册付款方式对象

在继续操作之前,您需要创建客户会话支付方式对象,用于设置SDK Lite集成以供注册使用。创建支付方式对象时,您需要定义将为客户注册提供的支付方式。

📘

重要

客户会话和注册支付方式对象必须在服务器端创建,以确保私有API密钥的安全性。支付方式类型需在服务器端设置,这与其他集成方式不同——其他集成方式可能允许在客户端设置该参数。

服务器端示例

在后端创建客户会话和注册支付方式。这将确保您的私有API密钥安全无虞。

// 1. Create customer session
const customerSession = await fetch(
  "https://api-sandbox.y.uno/v1/customers/sessions",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      customer_id: "your-customer-id",
      country: "US",
    }),
  }
).then((res) => res.json());

// 2. Create enrollment payment method
const enrollment = await fetch(
  `https://api-sandbox.y.uno/v1/customers/sessions/${customerSession.id}/payment-methods`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      type: "CARD",
    }),
  }
).then((res) => res.json());

// Return customerSession to your client
return customerSession;

客户端示例

收到后 customerSession 从您的服务器initialize SDK,并在客户端挂载注册表单。

// Initialize Yuno SDK
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

// Mount the enrollment form
yuno.mountEnrollmentLite({
  customerSession, // Received from your server
  countryCode: "US",
  language: "en",
  showLoading: true,
  onLoading: (args) => {
    console.log(args);
  },
});
📘

验证

如果您想在注册前验证卡片(零值授权),可以填写 verify 结构,同时为客户会话定义支付方法对象。

第 4 步:安装注册灯

配置和安装步骤与 Enrollment Lite 相同。使用 yuno.mountEnrollmentLite 函数并提供必要的参数。下表列出了所有参数及其说明。

参数说明
customerSession指当前payment的 客户会议.例如 e15648b0-fcd5-4799-a14c-cc463ae8a133.
country_code支付流程的国家。使用一个 ENUM 值;参见 覆盖国家.
language支付表格的语言。使用任何列出的代码。 支持的语言.例如 en-US默认使用浏览器语言(若可用)。
showLoading控制支付流程中Yuno加载/旋转图标页面的可见性。
onLoading需要接收有关服务器调用或加载事件的通知。
elementSelector用于挂载Yuno SDK的HTML元素。
card为信用卡表单定义特定设置。
yunoEnrollmentStatus注册结束后回调;接收 vaultedTokenstatus状态选项: CREATED, EXPIRED, REJECTED, READY_TO_ENROLL, ENROLL_IN_PROCESS, UNENROLL_IN_PROCESS, ENROLLED, DECLINED, CANCELED, ERROR, UNENROLLED.
issuersFormEnable启用发行人表格(银行列表)。
texts支付表单按钮的自定义文本,以匹配您应用程序的语言或品牌标识。
card.isCreditCardProcessingOnly可选。强制将卡交易仅作为信用卡交易处理——适用于兼具信用卡和借记卡功能的卡片。

下一个代码块提供了一个 Enrollment Lite 参数配置和安装的示例。

yuno.mountEnrollmentLite({
  customerSession: 'e15648b0-fcd5-4799-a14c-cc463ae8a133',
  /**
   * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage-yuno-sdk
   */
  country_code: country,
  /**
  * Language for payment forms (see Supported languages)
  * Defaults to browser language when available
  */
  language: 'en-US',
  /**
   * Hide or show the Yuno loading/spinner page
   * Default is true
   * @optional
   */
  showLoading: true,
  /**
   * Required if you'd like to be informed if there is a server call
   * @param { isLoading: boolean, type: 'DOCUMENT' | 'ONE_TIME_TOKEN'  } data
   * @optional
   */
  onLoading: (args) => {
    console.log(args);
  }
  /**
   *  API card
   *  @optional
   */
  card: {
    /**
     * Mode render card can be step or extends
     * Default extends
     */
    type: "extends",
    /**
     * Write custom CSS to style the card form. Your CSS will be injected into the iframe.
     * Example:
     * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
     *  .Yuno-front-side-card__name-label {
     *    color: red !important;
     *    font-family: 'Luckiest Guy' !important;
     *   }`
     */
    styles: '',
    /**
     * Show checkbox for save/enroll card
     * Default is false
     */
    cardSaveEnable: false,
    /**
     * Custom texts in Card forms buttons
     * Example:
     *
     *  texts: {
     *    cardForm?: {
     *      enrollmentSubmitButton?: string;
     *       paymentSubmitButton?: string;
     *     }
     *     cardStepper?: {
     *       numberCardStep?: {
     *         nextButton?: string;
     *       },
     *       cardHolderNameStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       expirationDateStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       cvvStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       }
     *     }
     *  }
     */
    texts: {},
    /**
     * Hide or show the document fields into card form
     * Default is true
     * @optional
     */
    documentEnable: true,
  },
  /**
   * Call back is called with the following object
   * @param {{
   *  status: 'CREATED'
   *    | 'EXPIRED',
   *    | 'REJECTED',
   *    | 'READY_TO_ENROLL',
   *    | 'ENROLL_IN_PROCESS',
   *    | 'UNENROLL_IN_PROCESS',
   *    | 'ENROLLED',
   *    | 'DECLINED',
   *    | 'CANCELED',
   *    | 'ERROR',
   *    | 'UNENROLLED',
   *  vaultedToken: string,
   * }}
   */
  yunoEnrollmentStatus: ({ status, vaultedToken}) => {
    console.log('status', { status, vaultedToken})
  },
  /**
   * If this is called the SDK should be mounted again
   * @param { error: 'CANCELED_BY_USER' | any }
   * @optional
   */
  yunoError: (error) => {
    console.log('There was an error', error)
  },
});

continuePayment 返回值或空

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

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

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

📘

演示应用程序

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

补充功能

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

装载机

控制装载机的使用。

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

表格渲染模式

参数说明
renderMode决定支付表单的显示方式。
- type: modalelement.
- elementSelector表单渲染的元素(若 typeelement).
elementSelectortypeelement.指定挂载 Yuno SDK 的位置。
- 字符串(已弃用)用于安装SDK的ID或选择器。
- 对象提供 apmForm (APM显示的位置)和 actionForm (用于打开模态窗口以完成供应商步骤的按钮,例如PIX二维码)
yuno.startCheckout({
  renderMode: {
    /**
     * Type can be one of `modal` or `element`
     * By default the system uses 'modal'
     * It is optional
     */
    type: "modal",
    /**
     * Element where the form will be rendered.
     * It is optional
     * Can be a string (deprecated) or an object with the following structure:
     * {
     *   apmForm: "#form-element",
     *   actionForm: "#action-form-element"
     * }
     */
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

下面的截图展示了不同渲染模式的区别 modalelements 查看付款方式列表。

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

卡片形式配置

参数说明
card定义信用卡表单的设置:
- type: stepextends.
- styles编写自定义CSS来设置卡片表单样式;您的CSS将被注入到iframe中。
- texts卡片表单按钮的自定义文本。
yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    texts: {},
  },
});

文本payment 表格按钮

参数说明
texts为支付表单按钮提供自定义文本,以匹配您应用程序的语言或品牌。
yuno.startCheckout({
  texts: {
    customerForm?: {
      submitButton?: string;
    }
    paymentOtp?: {
      sendOtpButton?: string;
    }
  }
})

SDK 定制

使用SDK 定制功能更改 SDK 外观,使其与您的品牌相匹配。

保持更新

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