patToken,交给小部件,结果用户走开了——或者你的系统在一分钟后取消了订单。该令牌会一直有效,直到你签发的 exp 到期,因此如果没有撤销的方法,用户之后可能回来并完成一个你不再需要的支付。
terminateWidgetSession 在服务端结束会话。下次用户在小部件内进行操作时会被拒绝,且任何针对该会话的付款尝试都会被拒绝。
先决条件: 你的应用程序用于 Basic Auth 的 API Key,以及你签发的操作员令牌或其
jti。认证
此变更使用你应用程序的凭据进行认证,而不是用户访问令牌——与您用于generateUserAccessToken 的 Basic 头相同:
app_id:apiSecret 对。请使用与签发该操作员令牌的 apiSecret 属于同一应用的密钥。
你只能终止与你进行认证的应用所属的会话。由其他应用签发的 jti 不会受到你的调用影响——你将获得一个成功响应,其中 wasActive: false,而该应用的会话会继续运行。
Basic 认证不适用于状态为 PERSONAL 的应用。
标识会话
提供操作员令牌或其jti 二选一。至少需要一个。
- 按令牌(首选)
- 按 jti
传入你交给小部件的同一个
patToken。它会用你应用的密钥进行验证,因此不属于你的令牌会被直接拒绝。已过期的令牌仍会被接受——终止一个已过期的会话是无害的,这也意味着你在调用前无需自己跟踪过期时间。令牌自身的 exp 也会限定终止被记忆的时长,这就是在你仍持有令牌时这是更佳选项的原因。jti 被视为对其的断言——与令牌自身不一致的 jti 会被拒绝,而不是被静默忽略,从而避免混淆导致终止错误的会话。
参数
input(TerminateWidgetSessionInput!):标识要终止的会话。
TerminateWidgetSessionInput 字段
示例 mutation
cURL 示例
示例响应
响应字段
wasActive: false 表示成功,而非失败。 当用户从未打开过小部件时,这是常见答案——这也是取消的最安全时机。终止一个从未被打开的会话是完全支持的,并且是撤销你已交付的支付的推荐方式。何时会拒绝终止
终止是幂等的——再次终止已被终止的会话也会成功。仅在两种情况下会被拒绝,这两种情况都意味着资金问题已定:
你可能看到的其他错误:
用户所见
终止会在用户下一次在小部件内进行导航或刷新时生效。它不会关闭已渲染的界面。 当用户下一次操作时,会看到“Session ended”的消息,注明你的应用并告知他们关闭窗口并从你的产品重新开始。若他们已经进入确认支付的步骤,该确认会以同样的消息被拒绝,且该会话的付款会在服务端以WidgetSessionTerminated(WIDGET-005,410)被拒绝。
终止会被记忆多久
被终止的会话会在其本可被使用的时长内被拒绝:- 按令牌终止——直到令牌自身的
exp,且至少为一小时。 - 仅按
jti终止——为 30 天。操作员令牌的签发时长没有上限,因此在没有可读取的exp时,会将终止记录保留远超任何可行的会话生命周期。
后续步骤
设置你的服务器
生成本变更所需的
patToken 和 jti。嵌入小部件
Script 标签、初始化调用、按钮绑定。
嵌入式小部件概览
小部件会话、OAuth 授权与预先批准的交易令牌如何协同工作。
幂等性
为什么每个资金流动的调用都需要唯一的
jti。