Skip to main content
你生成了一个 patToken,交给小部件,结果用户走开了——或者你的系统在一分钟后取消了订单。该令牌会一直有效,直到你签发的 exp 到期,因此如果没有撤销的方法,用户之后可能回来并完成一个你不再需要的支付。 terminateWidgetSession 在服务端结束会话。下次用户在小部件内进行操作时会被拒绝,且任何针对该会话的付款尝试都会被拒绝。
先决条件: 你的应用程序用于 Basic Auth 的 API Key,以及你签发的操作员令牌或其 jti

认证

此变更使用你应用程序的凭据进行认证,而不是用户访问令牌——与您用于 generateUserAccessTokenBasic 头相同:
从开发者控制台原样发送该 API Key;它已进行 base64 编码,并会解码为服务器校验的 app_id:apiSecret 对。请使用与签发该操作员令牌的 apiSecret 属于同一应用的密钥。
Staging 和 live 是相互独立的应用与凭据。来自错误环境的密钥会返回 401,其消息与格式错误的密钥相同——完整检查清单参见 If the token request returns 401
你只能终止与你进行认证的应用所属的会话。由其他应用签发的 jti 不会受到你的调用影响——你将获得一个成功响应,其中 wasActive: false,而该应用的会话会继续运行。 Basic 认证不适用于状态为 PERSONAL 的应用。

标识会话

提供操作员令牌或其 jti 二选一。至少需要一个。
传入你交给小部件的同一个 patToken。它会用你应用的密钥进行验证,因此不属于你的令牌会被直接拒绝。已过期的令牌仍会被接受——终止一个已过期的会话是无害的,这也意味着你在调用前无需自己跟踪过期时间。令牌自身的 exp 也会限定终止被记忆的时长,这就是在你仍持有令牌时这是更佳选项的原因。
只要两者描述的是同一会话,同时提供也是允许的。若同时提供,以令牌为准,jti 被视为对其的断言——与令牌自身不一致的 jti 会被拒绝,而不是被静默忽略,从而避免混淆导致终止错误的会话。

参数

  • inputTerminateWidgetSessionInput!):标识要终止的会话。

TerminateWidgetSessionInput 字段

示例 mutation

cURL 示例

示例响应

响应字段

wasActive: false 表示成功,而非失败。 当用户从未打开过小部件时,这是常见答案——这也是取消的最安全时机。终止一个从未被打开的会话是完全支持的,并且是撤销你已交付的支付的推荐方式。

何时会拒绝终止

终止是幂等的——再次终止已被终止的会话也会成功。仅在两种情况下会被拒绝,这两种情况都意味着资金问题已定: 你可能看到的其他错误:

用户所见

终止会在用户下一次在小部件内进行导航或刷新时生效。它不会关闭已渲染的界面。 当用户下一次操作时,会看到“Session ended”的消息,注明你的应用并告知他们关闭窗口并从你的产品重新开始。若他们已经进入确认支付的步骤,该确认会以同样的消息被拒绝,且该会话的付款会在服务端以 WidgetSessionTerminatedWIDGET-005410)被拒绝。
仅靠终止本身并不能阻止已开始执行的付款——这种情况会返回 409,你应等待完成或失败事件,而不是假定资金被拦截。

终止会被记忆多久

被终止的会话会在其本可被使用的时长内被拒绝:
  • 按令牌终止——直到令牌自身的 exp,且至少为一小时。
  • 仅按 jti 终止——为 30 天。操作员令牌的签发时长没有上限,因此在没有可读取的 exp 时,会将终止记录保留远超任何可行的会话生命周期。
在该时间窗口之后,记录会被丢弃。实际上此时操作员令牌早已过期,因此该会话无论如何都无法被使用。

后续步骤

设置你的服务器

生成本变更所需的 patTokenjti

嵌入小部件

Script 标签、初始化调用、按钮绑定。

嵌入式小部件概览

小部件会话、OAuth 授权与预先批准的交易令牌如何协同工作。

幂等性

为什么每个资金流动的调用都需要唯一的 jti