服务与 Host

Gateway 的公开流量面彼此隔离。每个客户端应绑定一个明确的 base URL、credential kind 和签名 service namespace。

服务	用途	接受的凭证	最小 Scope 示例
Invoice	代收、卡支付、Tokenization 写操作	Invoice account secret	invoices:write
Transfer	代付写操作	Transfer account secret	transfers:write
Query	所有商户查询操作	Invoice 或 Transfer account secret	invoices:read / transfers:read / accounts:read
Merchant Webhook	PSP 向商户推送事件	PSP 事件签名	不适用
Provider Webhook	上游通道回调 PSP	Provider 签名	商户不得调用
Hosted Checkout	托管收银台订单与状态	会话或托管订单令牌	不适用

强制隔离规则

• Invoice Host 不接受 Transfer credential。
• Transfer Host 不接受 Invoice credential。
• Query Host 只有读路由，即使凭证有写 Scope 也不能执行写操作。
• Provider Webhook Host 不接受商户账户密钥。
• Checkout URL 应使用 Invoice 响应返回的地址，不要自行拼接。

服务或凭证类型不匹配时会 fail-close，通常返回 401；认证成功但 Scope 不足时通常返回 403。

推荐客户端结构

paymentGateway
├── invoice  → PSP_INVOICE_BASE_URL  + invoice credential
├── transfer → PSP_TRANSFER_BASE_URL + transfer credential
└── query    → PSP_QUERY_BASE_URL    + invoice/transfer credential

不要配置全局 PSP_BASE_URL 后动态拼服务路径，这会放大凭证误用和错误 Host 调用的风险。