接入
HTP 快捷登录
用 OpenID Connect 登录用户，获取用于收付款的 sub。
支付接口只通过 OIDC sub 识别用户。请先接入 HTP 快捷登录，并保存每个用户的 sub。
端点
用发现文档配置你的 OIDC 库：
http
GET /.well-known/openid-configuration| 用途 | 路径 |
|---|---|
| 授权 | /oauth2/authorize |
| 令牌 | /oauth2/token |
| 用户信息 | /oauth2/userinfo |
| 公钥（JWKS） | /oauth2/jwks |
| 撤销 | /oauth2/revoke |
授权码模式 + PKCE S256（SPA / 原生 App 必须，Web 推荐）。ID Token 使用 RS256 签名。客户端认证：client_secret_basic（推荐）、client_secret_post，公开客户端为 none。
Scope
| Scope | Claims |
|---|---|
openid（必填） |
sub |
profile |
name、given_name、family_name、nickname、picture、gender、birthdate、updated_at |
email |
email、email_verified —— 需审核 |
phone |
phone_number、phone_number_verified —— 需审核 |
offline_access |
返回 refresh_token |
开放平台 App 默认可用 openid profile offline_access。
流程
http
GET /oauth2/authorize
?response_type=code
&client_id=<client_id>
&redirect_uri=https%3A%2F%2Fshop.example.com%2Fauth%2Fhtp%2Fcallback
&scope=openid%20profile%20offline_access
&state=<state>
&nonce=<nonce>
&code_challenge=<code_challenge>
&code_challenge_method=S256回调时校验 state 和 iss，然后用授权码换取令牌（只能使用一次，5 分钟内有效）：
bash
curl -X POST /oauth2/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=https://shop.example.com/auth/htp/callback \
-d code_verifier=<code_verifier>校验 id_token（用 JWKS 验签，校验 iss、aud = 你的 client_id、exp、nonce），然后读取 sub。
sub 是 pairwise 的
- 同一开发者的所有 App 拿到同一用户的同一个
sub，可以在你的多个 App 间共享用户。 - 不同开发者拿到的
sub不同 —— 无法跨开发者关联用户。 sub永久不变。请与用户记录一起保存，并作为payer_sub/payee_sub传入。
用户可以取消授权
用户可在 HTP App 的「已授权应用」中移除你的 App。之后 refresh token 和 userinfo 失效，你也无法再向该用户收款或付款（USER_NOT_AUTHORIZED），直到用户重新登录。
沙箱 App
App 发布前，只有你本人和测试用户能登录，其他人返回 access_denied。登录页会向用户标注该应用尚未经过 HTP 审核。