服务器到服务器 Vault 令牌化

使用 Hyperswitch Vault 服务实现 PCI 合规商户的服务器到服务器令牌化

从服务器直接进行安全卡片令牌化

将支付卡片从你的服务器直接令牌化到 Hyperswitch 的 Vault 服务，绕过客户端令牌化。这种服务器到服务器的方法可以提升安全性和灵活性，非常适合需要以编程方式管理支付方式的 PCI 合规商户。

核心功能

  • 完整的令牌管理 —— 直接从服务器创建、检索、更新和删除支付令牌。
  • PSP 和网络令牌化 —— 通过单个 API 同时生成 PSP 令牌和网络令牌。
  • 安全存储 —— 将令牌安全地存储在 Hyperswitch 的 Vault 中。
  • 降低前端复杂度 —— 将令牌化流程移至后端，减少对前端的依赖。

前置条件

要实现服务器到服务器令牌化，你需要：

  • PCI DSS 合规性以安全处理卡数据： 确保你具备处理原始卡数据的 PCI 合规性。
  • 安全的 API 身份验证以保护交易： 在 Hyperswitch 控制台的 Developers —> API Keys 部分生成你的 Hyperswitch API 密钥。
  • 健壮的错误处理机制： 针对令牌化失败情况实现必要的异常处理。

工作原理

  1. 收集卡片信息 —— 你的服务器收集卡片信息（需要 PCI 合规性）。
  2. 发送令牌化请求 —— 将卡片信息通过 POST /payment_methods 请求发送。
  3. 令牌创建与验证 —— Hyperswitch 验证请求并在 Vault 中生成安全令牌。
  4. PSP 和网络令牌化（可选） —— 如果你在 Hyperswitch 控制台配置了 PSP 和/或网络令牌化，传入相关参数即可自动生成对应令牌。
  5. 接收支付方式 ID —— 返回一个 pm_id，用于后续支付。

服务器到服务器令牌化的 API 请求

1. 创建客户信息

  • 接口： POST /customers
  • 作用： 创建客户信息，以便存储他们的支付方式。
  1. curl --location 'http://sandbox.hyperswitch.io/v2/customers' \
  2. --header 'Content-Type: application/json' \
  3. --header 'x-profile-id: <profile-id>' \
  4. --header 'api-key: <api_key>' \
  5. --data-raw '{   
  6.     "merchant_reference_id": "customer_1742551597",
  7.     "name": "John Doe",
  8.     "email": "guest@example.com",
  9.     "phone": "999999999",
  10.     "phone_country_code": "+65",
  11.     "description": "First customer",
  12.     "default_billing_address": {
  13.         "line1": "1467",
  14.         "line2": "Harrison Street",
  15.         "city": "San Francisco",
  16.         "state": "California",
  17.         "zip": "94122",
  18.         "country": "US",
  19.         "first_name": "Joseph",
  20.         "last_name": "Doe"
  21.     },
  22.     "default_shipping_address": {
  23.         "line1": "1467",
  24.         "line2": "Harrison Street",
  25.         "city": "San Francisco",
  26.         "state": "California",
  27.         "zip": "94122",
  28.         "country": "US",
  29.         "first_name": "Joseph",
  30.         "last_name": "Doe"
  31.     },
  32.     "metadata": {
  33.         "udf1": "value1",
  34.         "new_customer": "true",
  35.         "login_date": "2019-09-10T10:11:12Z"
  36.     }
  37. }'

2. 创建支付方式令牌

  • 接口： POST /payment_methods
  • 作用： 为卡片生成令牌。
  1. curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
  2. --header 'Content-Type: application/json' \
  3. --header 'x-profile-id: <profile-id>' \
  4. --header 'api-key: <api-key>' \
  5. --data '{
  6.   "payment_method_type": "card",
  7.   "payment_method_subtype": "credit",
  8.   "metadata": {},
  9.   "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  10.   "payment_method_data": {
  11.     "card": {
  12.       "card_number": "4111111145551142",
  13.       "card_exp_month": "10",
  14.       "card_exp_year": "25",
  15.       "card_holder_name": "John Doe",
  16.       "card_cvc": "242"
  17.     }
  18.   },
  19.   "billing": {
  20.     "address": {
  21.       "city": "New York",
  22.       "country": "US",
  23.       "line1": "123, King Street",
  24.       "zip": "08807",
  25.       "state": "New York",
  26.       "first_name": "John",
  27.       "last_name": "Doe"
  28.     },
  29.     "phone": {
  30.       "number": "9123456789",
  31.       "country_code": "+1"
  32.     },
  33.     "email": "abc@gmail.com"
  34.   }
  35. }'

a. 同时生成 PSP 令牌

在相同的接口请求中，通过添加 psp_tokenization 参数生成 PSP 令牌：

  1. curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
  2. --header 'Content-Type: application/json' \
  3. --header 'x-profile-id: <profile-id>' \
  4. --header 'api-key: <api-key>' \
  5. --data '{
  6.   "payment_method_type": "card",
  7.   "payment_method_subtype": "ach",
  8.   "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  9.   "payment_method_data": {
  10.     "card": {
  11.       "card_number": "4111111145551142",
  12.       "card_exp_month": "10",
  13.       "card_exp_year": "25",
  14.       "card_holder_name": "John Doe",
  15.       "card_cvc": "242"
  16.     }
  17.   },
  18.   "psp_tokenization": {
  19.     "tokenization_type": "single_use",
  20.     "connector_id": "<string>"
  21.   }
  22. }'

b. 同时生成网络令牌

通过添加 network_tokenization 参数生成网络令牌：

  1. curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
  2. --header 'Content-Type: application/json' \
  3. --header 'x-profile-id: <profile-id>' \
  4. --header 'api-key: <api-key>' \
  5. --data '{
  6.   "payment_method_type": "card",
  7.   "payment_method_subtype": "ach",
  8.   "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  9.   "payment_method_data": {
  10.     "card": {
  11.       "card_number": "4111111145551142",
  12.       "card_exp_month": "10",
  13.       "card_exp_year": "25",
  14.       "card_holder_name": "John Doe",
  15.       "card_cvc": "242"
  16.     }
  17.   },
  18.   "network_tokenization": {
  19.     "enable": "Enable"
  20.   }
  21. }'

3. 获取支付方式令牌

  • 接口： GET /payment_methods/:pm_id
  • 作用： 获取现有令牌详情。
  1. curl --location --globoff 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
  2. --header 'x-profile-id: <profile-id>' \
  3. --header 'api-key: <api-key>'

4. 更新支付方式令牌

  • 接口： PATCH /payment_methods/:pm_id/update_saved_payment_method
  • 作用： 修改令牌信息。
  1. curl --location --globoff --request PATCH 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}/update-saved-payment-method' \
  2. --header 'Content-Type: application/json' \
  3. --header 'x-profile-id: <profile-id>' \
  4. --header 'api-key: <api-key>' \
  5. --data '{
  6.   "payment_method_data": {
  7.     "card": {
  8.       "card_holder_name": "John Doe"
  9.     }
  10.   }
  11. }'

5. 删除支付方式令牌

  • 接口： DELETE /payment_methods/:pm_id
  • 作用： 从 Vault 中删除令牌。
  1. curl --location --globoff --request DELETE 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
  2. --header 'x-profile-id: <profile-id>' \
  3. --header 'api-key: <api-key>'