服务器到服务器 Vault 令牌化

服务器到服务器 Vault 令牌化

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

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

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

核心功能

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

前置条件

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

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

工作原理

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

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

1. 创建客户信息

接口： POST /customers
作用： 创建客户信息，以便存储他们的支付方式。

curl --location 'http://sandbox.hyperswitch.io/v2/customers' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api_key>' \
--data-raw '{   
    "merchant_reference_id": "customer_1742551597",
    "name": "John Doe",
    "email": "guest@example.com",
    "phone": "999999999",
    "phone_country_code": "+65",
    "description": "First customer",
    "default_billing_address": {
        "line1": "1467",
        "line2": "Harrison Street",
        "city": "San Francisco",
        "state": "California",
        "zip": "94122",
        "country": "US",
        "first_name": "Joseph",
        "last_name": "Doe"
    },
    "default_shipping_address": {
        "line1": "1467",
        "line2": "Harrison Street",
        "city": "San Francisco",
        "state": "California",
        "zip": "94122",
        "country": "US",
        "first_name": "Joseph",
        "last_name": "Doe"
    },
    "metadata": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}'

2. 创建支付方式令牌

接口： POST /payment_methods
作用： 为卡片生成令牌。

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "credit",
  "metadata": {},
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
    "card": {
      "card_number": "4111111145551142",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "John Doe",
      "card_cvc": "242"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "123, King Street",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "abc@gmail.com"
  }
}'

a. 同时生成 PSP 令牌

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

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
    "card": {
      "card_number": "4111111145551142",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "John Doe",
      "card_cvc": "242"
    }
  },
  "psp_tokenization": {
    "tokenization_type": "single_use",
    "connector_id": "<string>"
  }
}'

b. 同时生成网络令牌

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

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
    "card": {
      "card_number": "4111111145551142",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "John Doe",
      "card_cvc": "242"
    }
  },
  "network_tokenization": {
    "enable": "Enable"
  }
}'

3. 获取支付方式令牌

接口： GET /payment_methods/:pm_id
作用： 获取现有令牌详情。

curl --location --globoff 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>'

4. 更新支付方式令牌

接口： PATCH /payment_methods/:pm_id/update_saved_payment_method
作用： 修改令牌信息。

curl --location --globoff --request PATCH 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}/update-saved-payment-method' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_data": {
    "card": {
      "card_holder_name": "John Doe"
    }
  }
}'

5. 删除支付方式令牌

接口： DELETE /payment_methods/:pm_id
作用： 从 Vault 中删除令牌。

curl --location --globoff --request DELETE 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>'