支付处理器规范指南

简介

本指南定义指定 UCP 支付处理器的标准结构和词汇，以确保一致性、完整性和清晰度。

目的

支付处理器实现平台、商家和支付提供商之间的 “N 对 N” 互操作性。规范的处理器必须回答：

  • 谁参与？ 涉及哪些参与者及其角色
  • 有哪些先决条件？ 需要什么入门或设置
  • 如何配置？ 宣告或使用什么配置
  • 如何执行？ 遵循什么协议

核心元素

参与者

参与支付处理器生命周期的不同参与者：

参与者角色
商家宣告处理器配置，处理支付工具
平台发现处理器，获取支付工具，提交结账
令牌化器（可选）存储原始凭证并发行令牌凭证
PSP（可选）代表商家处理支付

先决条件

参与者在参与之前必须完成的入门、设置或配置：

签名：

PREREQUISITES(participant, onboarding_input) → prerequisites_output

输出包括：

  • 身份（PaymentIdentity 格式中的 access_token）
  • 额外配置、凭证或设置

处理器宣告

商家宣告的配置，以指示对此处理器的支持：

{
  "id": "handler_instance_id",
  "name": "com.example.handler",
  "version": "2026-01-11",
  "spec": "https://example.com/ucp/handler",
  "config_schema": "https://example.com/ucp/handler/config.json",
  "instrument_schemas": [
    "https://example.com/ucp/handler/instruments/card.json"
  ],
  "config": {
    // 处理器特定配置
  }
}

工具获取

平台遵循的获取支付工具的协议：

签名：

INSTRUMENT_ACQUISITION(
  platform_prerequisites_output,
  handler_declaration,
  binding,
  buyer_input
) → checkout_instrument

处理

参与者为接收到的支付工具执行的步骤：

签名：

PROCESSING(
  identity,
  checkout_instrument,
  binding,
  transaction_context
) → processing_result

最佳实践

Schema 设计

实践描述
扩展而非重新发明使用 allOf 组合基本 schema
对鉴别器使用 const将 credential.type 定义为 const
提前验证在最终确定之前在稳定 URL 发布 schema
包括过期为令牌凭证包含 expiry 或 ttl

文档

实践描述
展示而非仅讲述包括完整的 JSON 示例
记录错误情况指定错误处理
独立版本控制处理器版本独立于 UCP 演变

安全

实践描述
需要绑定通过 binding 将凭证绑定到特定结账
最小化凭证暴露设计流程以最小化原始凭证暴露
指定令牌生命周期记录单次使用、时间限制或会话范围

一致性检查表

发布前，验证：

  • 使用标准模板结构
  • 所有 [必需] 部分都存在
  • 列出所有参与者及其角色
  • 为每个参与者记录先决条件
  • 身份映射到 PaymentIdentity 结构
  • 记录配置、工具和凭证 schema
  • 使用示例枚举协议步骤
  • 指定绑定要求
  • 列出安全要求
  • 处理器名称遵循反向 DNS 约定

另请参阅