Skip to main content
这些工具是 Wallet Service 和 Browser Pay 之外的补充能力。已连接服务端的当前规则为用户请求选择 Catalog 或 UCP Checkout 时,使用对应工具。搜索结果不代表用户已授权购买。 本页介绍主要参数,完整 schema 通过 tools/list 获取;工具调用方式见 MCP 连接与 OAuth。即使工具没有额外 Scope 要求,也需要正常的 MCP 认证连接。

搜索与商品详情

搜索商品

tools/call 参数示例:
注册商户范围不能与外部门店或 provider 范围混用。结果可能包含 groups、provider_results 和精确的商品 target 对象。调用 get_product 时保留原始 target;门店 ID 不等于注册商户 ID。 纯搜索不创建购买授权,也不发起支付。结账前确定商品规格和必选项。按返回或解析结果注明的单位使用价格,已经是最小货币单位的金额不要再乘以 100。

UCP Checkout

用户选择 UCP Checkout 购买后,先按已连接服务端的规则处理购买授权。如果指定预算需要预授权,在搜索前激活匹配的购买指令;未指定预算时,可先由结账返回实际总额,再完成授权。
  1. 从 Catalog 获取确定的商品,或解析商品链接。
  2. 确定 SKU、选项、数量和履约要求。
  3. 调用 create_checkout,按 next_action 补充信息、授权消费或确认摘要。
  4. 使用 update_checkout 修改当前结账支持的字段,重新查看并确认更新后的摘要。
  5. 针对当前确认调用一次 complete_checkout。结果仍在等待或响应丢失时,读取 get_operation。
  6. 查询返回的 UCP 订单;数字商品按需等待交付。

主要结账参数

使用 create_checkout 的 items 形式时:
  • 注册商户:使用返回的商户 ID、商品 ID、数量与已选选项。价格由 Catalog 提供,省略外部 currency、商品 title 和 unitPriceMinor 字段。
  • 外部商品:商品 URL 放入 merchantUrl,提供 currency,并填写每件商品的准确 title 与 unitPriceMinor。保留结果返回的 order_channel_id。缺失信息先通过 get_product 或 parse_product_item 获取,再创建结账。
  • 履约:需配送的实物使用 PHYSICAL_GOODS_REQUIRES_SHIPPING 并提供完整配送信息;不需配送时使用 NO_SHIPPING_REQUIRED。履约类型不明确时先向用户确认。
create_checkout 只准备结账,不完成支付。update_checkout 会使旧确认失效。complete_checkout 使用当前确认标识,不能在此替换金额或支付卡。兼容字段 paymentInstrumentId 在 Checkout 中被忽略,结账使用钱包默认卡。 购买授权工具及金额单位见 Wallet Service 工具。Operation 标识、版本和恢复方式见 Operation。

订单与交付

部分服务端版本将此 UCP 订单读取工具命名为 get_ucp_order。调用时使用当前连接的服务端 tools/list 返回的准确名称。 支付完成与交付完成是不同状态。查询订单或等待交付不会重试支付。 UCP 订单 ID 与 Clink 直接支付订单 ID 指向不同记录,不能互换,也不要假设 UCP 订单 ID 可以直接传给 Clink 退款工具。这组 UCP 工具没有提供通用的取消订单或退款操作。

区分支付流程

UCP Checkout 通过 complete_checkout 及其 Operation 完成。Browser Pay 获取凭证后,在商户网站付款,再通过 confirm_result 上报观察到的结果。UCP Checkout 完成后不要调用 Browser Pay 的 confirm_result。