Vault SDK 集成

使用 Hyperswitch Vault 服务的 Vault SDK 进行卡片令牌化

使用 Hyperswitch 的 PCI 合规 Vault SDK 进行安全令牌化

Hyperswitch Vault SDK 为商户提供了一种安全解决方案，可以处理和存储支付信息，而无需承担 PCI DSS 合规的负担。通过使用 Hyperswitch 的 Vault 服务，商户可以安全地存储客户的支付方式（信用卡、数字钱包等），同时将敏感支付数据的暴露风险降到最低。

核心优势

  • 简化 PCI 合规性： 将敏感支付数据的存储交给 Hyperswitch 的安全 Vault，减少你的 PCI 范围。
  • 提升客户体验： 让客户保存和重复使用支付方式，加快结账速度。
  • 降低购物车放弃率： 为回头客启用一键支付，减少结账中断。
  • 安全令牌系统： 通过安全令牌访问保存的支付方式，而无需处理原始卡片数据。
  • 可定制 UI： 将预构建的、可自定义的支付方式管理界面集成到你的应用中。

Vault SDK 集成指南

本文档提供了将 Hyperswitch Vault SDK 集成到你的应用中的分步说明。

1. 服务端配置

首先，你需要在服务器上配置支付方式会话，以建立前端与 Hyperswitch Vault 之间的安全连接。

获取你的 API 密钥

在 Hyperswitch 控制台 的 Developers -> API Keys 部分生成你的 API 密钥。你需要 API 密钥 和 profile ID 用于服务器和客户端集成。

创建支付方式会话的接口

在你的服务器上添加一个接口来创建支付方式会话。该接口会将会话信息返回给你的客户端应用：

  1. // 创建支付方式会话
  2. const app = express();
  4. app.post(`/create-payment-methods-session`, async (req, res) => {
  5.   try {
  6.     const response = await fetch(
  7.       `https://sandbox.hyperswitch.io/v2/payment-methods-session`,
  8.       {
  9.         method: "POST",
  10.         headers: {
  11.           "Content-Type": "application/json",
  12.           "x-profile-id": "YOUR_PROFILE_ID",
  13.           Authorization: "api-key=YOUR_API_KEY",
  14.         },
  15.         body: JSON.stringify(req.body),
  16.       }
  17.     );
  19.     const data = await response.json();
  21.     res.send({
  22.       pmSessionId: data.id,
  23.       pmClientSecret: data.client_secret,
  24.     });
  25.   } catch (err) {
  26.     return res.status(400).send({
  27.       error: {
  28.         message: err.message,
  29.       },
  30.     });
  31.   }
  32. });

💡 注意： 将 YOUR_PROFILE_ID 和 YOUR_API_KEY 替换为你在 Hyperswitch 控制台生成的真实凭据。

2. 客户端集成（React）

服务器接口配置完成后，你需要将 Vault SDK 集成到客户端应用中。以下是 React 应用中的集成步骤。

2.1 安装所需的库

安装 Hyperswitch 的 JavaScript 和 React 库：

  1. $ npm install @juspay-tech/hyper-js
  2. $ npm install @juspay-tech/react-hyper-js

2.2 将 Hyperswitch 集成到 React 应用中

在 React 项目中导入所需的组件和 hooks：

  1. import React, { useState, useEffect } from "react";
  2. import { loadHyper } from "@juspay-tech/hyper-js";
  3. import { VaultSDK } from "@juspay-tech/react-hyper-js";

2.3 初始化 Hyperswitch 库

使用你的 publishable API 密钥 和 profile ID 配置库：

  1. const hyperPromise = loadHyper({
  2.   publishableKey: "YOUR_PUBLISHABLE_KEY",
  3.   profileId: "YOUR_PROFILE_ID",
  4. });

⚠️ 安全提示： publishableKey 可以在前端代码中暴露，但不要在前端包含你的 secret API 密钥。

2.4 获取会话详情

向服务器接口发送请求以创建新的支付方式会话：

  1. const [pmClientSecret, setPmClientSecret] = useState(null);
  2. const [pmSessionId, setPmSessionId] = useState(null);
  4. useEffect(() => {
  5.   fetch("/create-payment-methods-session", {
  6.     method: "POST",
  7.     headers: { "Content-Type": "application/json" },
  8.     body: JSON.stringify({ customer_id: "customer_id" }),
  9.   })
  10.   .then((res) => res.json())
  11.   .then((data) => {
  12.     setPmClientSecret(data.pmClientSecret);
  13.     setPmSessionId(data.pmSessionId);
  14.   });
  15. }, []);

✅ 重要： 将 "customer_id" 替换为实际的客户标识符，以便将保存的支付方式与客户关联。

2.5 初始化 VaultSDK 组件

将 loadHyper 返回的 promise 和会话详情传递给 VaultSDK 组件：

  1. const options = {
  2.   pmSessionId: pmSessionId,
  3.   pmClientSecret: pmClientSecret,
  4. };
  6. return (
  7.   <div className="App">
  8.     {pmSessionId && pmClientSecret && (
  9.       <VaultSDK options={options} hyper={hyperPromise}>
  10.         <VaultElementsForm />
  11.       </VaultSDK>
  12.     )}
  13.   </div>
  14. );

2.6 添加 Vault Elements

创建一个 VaultElementsForm 组件，并使用 VaultElement 显示保存的支付方式：

  1. const VaultElementsForm = () => {
  2.   return (
  3.     <div>
  4.       <h2>您的保存支付方式</h2>
  5.       <VaultElement id="vault-element" />
  6.     </div>
  7.   );
  8. };

✅ VaultElement 会嵌入一个带有动态表单的 iframe，显示保存的支付方式，允许客户安全地查看、管理和保存新的支付方式。