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 | 注册结束后回调;接收 vaultedToken 和 status状态选项: 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 返回值或空
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: modal 或 element.- elementSelector表单渲染的元素(若 type 是 element). |
elementSelector | 当 type 是 element.指定挂载 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",
},
},
});下面的截图展示了不同渲染模式的区别 modal 和 elements 查看付款方式列表。
您还可以为贺卡表单选择其中一个渲染选项、 step 和 extends:
卡片形式配置
| 参数 | 说明 |
|---|---|
card | 定义信用卡表单的设置: - type: step 或 extends.- 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 更新和版本历史。
27 天前已更新