tools/list 获取;工具调用方式见 MCP 连接与 OAuth。即使工具没有额外 Scope 要求,也需要正常的 MCP 认证连接。
搜索与商品详情
搜索商品
tools/call 参数示例:
注册商户范围不能与外部门店或 provider 范围混用。结果可能包含
groups、provider_results 和精确的商品 target 对象。调用 get_product 时保留原始 target;门店 ID 不等于注册商户 ID。
纯搜索不创建购买授权,也不发起支付。结账前确定商品规格和必选项。按返回或解析结果注明的单位使用价格,已经是最小货币单位的金额不要再乘以 100。
UCP Checkout
用户选择 UCP Checkout 购买后,先按已连接服务端的规则处理购买授权。如果指定预算需要预授权,在搜索前激活匹配的购买指令;未指定预算时,可先由结账返回实际总额,再完成授权。- 从 Catalog 获取确定的商品,或解析商品链接。
- 确定 SKU、选项、数量和履约要求。
- 调用
create_checkout,按next_action补充信息、授权消费或确认摘要。 - 使用
update_checkout修改当前结账支持的字段,重新查看并确认更新后的摘要。 - 针对当前确认调用一次
complete_checkout。结果仍在等待或响应丢失时,读取get_operation。 - 查询返回的 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。