指南
状态页面Dashboard预约演示
开始键入搜索...

安全字段 Payment

请按照本分步指南在您的应用程序中实施并启用 Yuno 的安全字段结账功能。

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

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

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

  1. 直接包含 HTML 脚本
  2. 动态 JavaScript 注入
  3. 安装 NPM 模块

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

📘

TypeScript 库

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

步骤 2：用公开密钥Initialize 安全字段

在您的 JavaScript 应用程序中，创建一个 Yuno 类提供一个有效的 PUBLIC_API_KEY:

const yuno = await YunoinitializePUBLIC_API_KEY)；
📘

证书

更多信息，请参阅全权证书页面： https://docs.y.uno/reference/authentication

步骤 3：开始结账

您将开始结账流程。为此，请使用 secureFields 功能，并提供必要的配置参数：

基本参数是 countrycode，它决定了付款程序的配置国家，以及 checkoutSession是指当前付款的结账会话。

参数

使用以下选项配置安全字段：

参数说明
countrycode该参数用于指定正在设置payment 流程的国家。使用 ENUM 值代表所需的国家代码。支持的国家及其相应代码的完整列表可在 覆盖国家 page.
checkoutSession指当前payment的 结账环节. Example: '438413b7-4921-41e4-b8f3-28a5a0141638'
installmentEnable此参数为可选参数，默认设置为 false。如果设置为 "true"，为账户设置的分期付款将显示为安全字段。
const secureFields = yuno.secureFields({
  countrycode: country,
  checkoutSession,
  installmentEnable: false
});
📘

客户和商家发起的交易

付款可以由客户（CIT）或商家（MIT）发起。有关其特点的更多信息，请参阅 "存储凭证"。

本页介绍的分步操作是指客户发起的不带重复选项的交易。通常用于一次性网上购物、店内购物、ATM 取款等。

步骤 4：安装安全字段

定义参数后，您将定义、配置和加载安全字段。对于每个安全字段，需要定义 name 和 options 在使用 secureFields.create 功能。

下表列出了所有可用配置：

参数说明
name可用的字段名称有cvv、pan 或expiration。
options.placeholder字段的默认占位符。
options.styles当前字段的其他 CSS 样式。
options.label字段可见标签。
options.showError定义是否显示错误。可用选项包括 true 和 false.
options.onChange可配置的辅助功能，在字段内容发生变化时运行。指示字段是否有错误或附加数据。
options.onBlur可配置的辅助功能，在输入模糊时运行。
options.validateOnBlur改变验证行为，通过在字段失去焦点后提供验证反馈来改善用户体验。这是一个可选参数，用于 false 为默认值。
options.onFocus可配置的辅助功能，将在聚焦输入时运行。
options.onRenderedSecureField可配置的辅助函数，将在元素完成渲染时运行。
options.errorMessage这样就可以定义字段的错误信息。
options.inputMode(仅限 V1.2+ 版本） 定义在移动设备上显示的键盘类型。可能的值 'numeric' (默认）或 'text'.

设置参数后，您将使用 render 功能，使用有效的 CSS 选择器 (#, ., [data-*]).

下面的代码块显示了三个安全字段的参数配置示例，当它们被加载时，字段就会显示给用户：

安全字段参数

参数说明
name字段类型："cvv"、"pan "或 "过期
options.placeholder输入框中显示的占位符文本
options.styles注入 iframe 的 CSS 样式。您可以通过编写 CSS
options.label字段的标签文本
options.showError是否显示错误信息
options.errorMessage自定义显示的错误信息
options.validateOnBlur是否在失去焦点时验证字段
options.onChange字段值发生变化时触发的回调函数。接收 {error, data} 其中 data 包含贺卡 IIN 信息和分期付款选择
options.onBlur字段失去焦点时触发的回调函数
options.onFocus字段获得焦点时触发的回调函数
options.onRenderedSecureField当安全字段完成渲染时触发的回调函数

回调onChange 可用的数据

当 onChange 回调被触发时， data 参数包含

  • 卡片 IIN 信息：发卡机构详细信息，包括计划、品牌、类型和发卡机构信息
  • 分期付款计划：账户的可用分期付款选项（如有配置
  • 加载国家: isCardIINLoading 和 isInstallmentLoading 布尔标志
const secureNumber = secureFields.create({
    name: 'pan',
    options: {
      placeholder: '0000 0000 0000 0000',
      styles: ``,
      label: 'Card Number',
      showError: true,
      errorMessage: "Custom Error",
      validateOnBlur: false,
      onChange: ({ error,data }) => {
        if (error) {
          console.log('error_pan')
        } else {
          console.log('not_error_pan')
        }
      },
      onBlur() {
        console.log('blur_pan')
      },
      onFocus: () => {
        console.log('focus_pan')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureNumber.render('#pan')

  const secureExpiration = secureFields.create({
    name: 'expiration',
    options: {
      placeholder: 'MM / YY',
      styles: ``,
      label: 'Card Expiration',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_expiration')
        } else {
          console.log('not_error_expiration')
        }
      },
      onBlur() {
        console.log('blur_expiration')
      },
      onFocus: () => {
        console.log('focus_expiration')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureExpiration.render('#expiration')


  const secureCvv = secureFields.create({
    name: 'cvv',
    options: {
      placeholder: 'CVV',
      styles: ``,
      label: 'CVV',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_cvv')
        } else {
          console.log('not_error_cvv')
        }
      },
      onBlur() {
        console.log('blur_cvv')
      },
      onFocus: () => {
        console.log('focus_cvv')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureCvv.render('#cvv')

下面的 GIF 演示了如何配置安全字段：

步骤 5：生成 OTT（一次性token

掌握所有用户信息后，就可以开始付款了。首先，您需要使用函数 secureFields.generateToken.由于这是一个异步函数，您可以使用 try/catch 以确保正确处理触发的错误。下面的token 展示了如何使用 vaultedToken 信息：

📘

使用拱顶Token的好处

当您使用 SDK 的保险库token 时，您在卡路由中配置的提供商的所有欺诈信息都会被收集并附加到一次性token中。此外，如果提供商需要，您还可以添加分期付款信息和安全代码。

生成Token 参数

参数说明
checkoutSession可选：不同的结账会话 ID 用于在支付错误后保留银行卡数据
cardHolderName必须填写：持卡人姓名
saveCard可选：是否为将来付款保存该卡
vaultedToken可选：如果您以前注册过付款方式，请使用该选项
installment可选：仅当账户配置了分期付款计划时才需要
const oneTimeToken = await secureFields.generateToken({
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

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

Create a one-time token with error handling:
const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

步骤 6：创建付款

收到一次性token后，您可以使用以下任一选项创建付款：

这两个选项都要求您提供 oneTimeToken 和 checkoutSession.由于创建付款可能会引发错误，Yuno 建议您在此处使用 try/catch 函数。

之后，您可以使用 yuno.mountStatusPayment 功能。下面的示例使用 createPayment 函数来创建付款，而 mountStatusPayment 以显示付款状态：

付款创建流程

  1. 创建Payment:使用 createPayment 函数使用一次性token 和结账会话
  2. 检查 SDK 操作:如果 sdk_action_required 为真，则调用 yuno.continuePayment() 以采取更多客户行动
  3. 安装状态:如果不需要 SDK 操作，请使用 yuno.mountStatusPayment() 显示付款状态

安装状态付款参数

参数说明
checkoutSession付款的结账会话 ID
countrycode付款流程的国家代码
language状态显示语言
yunoPaymentResult接收付款状态更新的回调函数
const payment = await createPayment({ oneTimeToken, checkoutSession })

if (payment.checkout.sdk_action_required) {
      yuno.continuePayment()
} else {
  yuno.mountStatusPayment({
    checkoutSession: checkoutSession,
    countrycode: 'US',
    language: 'en',
    yunoPaymentResult(data) {
      console.log('yunoPaymentResult', data)
    },
  })
}
📘

演示应用程序

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

补充功能

Yuno Secure Fields 提供额外的服务和配置，您可以用来改善客户体验：

配置和使用 TypeScript

要在 Yuno Secure Fields SDK 中使用 TypeScript，首先要通过 npm 安装类型定义：

npm install @yuno-payments/sdk-web-types

完成安装后，在 TypeScript 配置中包含类型定义。更新 tsconfig.json 文件中包含 @yuno-payments/sdk-web-types 在类型数组中，如下例所示：

{
  "compilerOptions": {
    "types": ["@yuno-payments/sdk-web-types"]
  }
}

安装并配置好类型定义后，就可以在代码中使用它们了。下面的代码块举例说明了如何initialize Yuno 和创建实例：

import { YunoInstance } from '@yuno-payments/sdk-web-types/dist/types';

const yunoInstance: YunoInstance = await Yuno.initialize('yourPublicApiKey');

记得更换 yourPublicApiKey 使用您的实际公共 API 密钥。

保留信用卡信息以重试付款

如果交易被拒绝，您可以在客户输入信用卡详细信息后，持续保存信用卡数据以重试付款。为此，您需要遵循以下步骤：

  1. 在步骤 5 中创建一次性token 时，添加以下代码块中的参数。这样就能接收客户在结账时提供的任何其他信息，如分期付款、文件类型或文件编号。
const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
})
  1. 如果交易被拒绝，您需要 i.创建一个新的结账会话。 ii.生成一个新的一次性token。在生成一次性token 时，将新的结账会话发送到 checkoutSession 参数。
  2. 继续使用新的结账和一次性token 与常规支付流程。

清除在卡片字段中输入的值

与前面的功能相关，商家可以设置清除在任何卡片字段中输入的信息。为此，需要执行以下方法 secureFieldInstance.clearValue()清除或删除每个字段。下面的示例说明了如何操作：

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.clearValue()

输入重点

商家可以将焦点设置在特定输入上。为此，需要执行方法 secureFieldInstance.focus()，针对您希望关注的每个字段。下面的代码块显示了一个示例：

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.focus()

强制验证

商家可以强制对特定输入进行验证。为此，需要执行方法 secureFieldInstance.validate()来验证每个字段。下面的代码块显示了一个示例：

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.validate()

设置自定义错误信息

商家可以在输入验证后自定义错误信息。为此，需要执行方法 secureFieldInstance.setError()，为每个字段设置自定义错误信息。下面的代码块显示了一个示例：

const secureFieldInstance = secureFields.create({...})
secureFieldInstancesetError('Custom error')

设置卡片类型

商家可以定义客户用于付款的卡类型。为此，您需要执行方法 secureFieldInstance.setCardType() 并为每种情况发送 "借记卡 "或 "贷记卡"。这对于双卡（同一张卡可用作信用卡或借记卡）非常有用，例如在巴西。下面的代码块显示了一个示例：

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.setCardType('CREDIT')

下一步是什么？

您可以访问 Yuno Web SDK 提供的其他功能：

  • SDK 定制：更改 SDK 外观，使其与您的品牌相匹配。
  • 付款状态：向用户提供有关付款过程的最新信息。

保持更新

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

3 个月前已更新