令牌化指南

概述

本指南供构建令牌化支付处理器的实现者使用，定义共享 API、安全要求和一致性标准。

核心概念

凭证流

令牌化处理器在源凭证和结账凭证之间转换：

平台拥有：              令牌化器           商家接收：
卡凭证        ──▶  /tokenize  ──▶         令牌凭证
(FPAN/DPAN)                                  (令牌)

令牌生命周期

策略描述用例
单次使用首次解令牌化后失效最安全；推荐
基于 TTL在固定持续时间后过期（例如 15 分钟）允许重试
会话范围在结账会话期间有效复杂流程

绑定

所有令牌化请求都需要 binding 对象：

字段必需描述
checkout_id是此令牌有效的结账会话
identity有条件要绑定的参与者身份

OpenAPI

POST /tokenize

将原始凭证转换为绑定到结账和身份的令牌。

请求：

POST /tokenize
Content-Type: application/json

{
  "credential": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4111111111111111",
    "expiry_month": 12,
    "expiry_year": 2026,
    "cvc": "123"
  },
  "binding": {
    "checkout_id": "abc123",
    "identity": {
      "access_token": "merchant_001"
    }
  }
}

响应：

{
  "token": "tok_abc123xyz789"
}

POST /detokenize

为有效令牌返回原始凭证。绑定必须匹配。

请求：

POST /detokenize
Content-Type: application/json
Authorization: Bearer {caller_access_token}

{
  "token": "tok_abc123xyz789",
  "binding": {
    "checkout_id": "abc123"
  }
}

响应：

{
  "type": "card",
  "card_number_type": "fpan",
  "number": "4111111111111111",
  "expiry_month": 12,
  "expiry_year": 2026,
  "cvc": "123"
}

安全要求

要求描述
需要绑定凭证必须绑定到 checkout_id 和 identity
验证绑定令牌化器必须在返回凭证之前验证绑定匹配
加密随机使用安全随机生成器；令牌必须不可猜测
足够长度最小 128 位熵
不可逆无法从令牌导出凭证
时间限制对用例执行适当的 TTL（通常 5-30 分钟）
优先单次使用尽可能在首次解令牌化后失效

处理器规范要求

发布处理器时，规范必须包括：

要求示例
唯一处理器名称com.example.tokenization_payment
端点 URL生产环境和沙箱基础 URL
身份验证要求OAuth 2.0、API 密钥等
入门流程参与者如何注册和接收身份
接受的凭证接受哪些凭证类型
令牌生命周期策略单次使用、TTL 或会话范围

一致性检查表

令牌化处理器符合要求如果：

  • 在稳定 URL 发布处理器规范并具有唯一名称
  • 根据 OpenAPI 实现 /tokenize 和/或 /detokenize
  • 定义身份验证和入门要求
  • 记录源和结账表单之间的凭证转换
  • 生成与 TokenCredential schema 兼容的令牌
  • 指定令牌生命周期策略
  • 在令牌化请求上需要带有 checkout_id 的 binding
  • 在解令牌化请求上验证 binding 匹配

参考资料

资源URL
令牌化 OpenAPIhttps://ucp.dev/handlers/tokenization/openapi.json
身份 Schemahttps://ucp.dev/schemas/shopping/types/payment_identity.json
绑定 Schemahttps://ucp.dev/schemas/shopping/types/binding.json
令牌凭证 Schemahttps://ucp.dev/schemas/shopping/types/token_credential.json

另请参阅