Skip to main content
你產生一個 patToken、把它交給 widget,而使用者走開了——或是你的系統在一分鐘後取消了訂單。該權杖會一直有效直到你簽署的 exp 到期為止,所以如果沒有撤銷的方法,使用者之後仍可能回來完成你已經不希望發生的付款。 terminateWidgetSession 會在伺服器端結束該工作階段。之後使用者在 widget 內的下一次操作會被拒絕,且任何針對該工作階段的撥款嘗試都會被拒絕。
先決條件: 你的應用程式 API Key(用於 Basic 認證),以及你簽發的 operator token 或其 jti。

認證

此 mutation 使用你的「應用程式」憑證進行認證,而不是使用者的 access token——與你用於 generateUserAccessToken 的 Basic 標頭相同:
從開發者主控台原樣送出 API Key;它已經過 base64 編碼,解碼後為伺服器檢查的 app_id:apiSecret 配對。請使用與簽署該 operator token 的 apiSecret 相同應用程式所對應的金鑰。
Staging 與正式環境是分開的應用程式,且有各自的憑證。使用錯誤環境的金鑰會回傳 401,訊息與格式錯誤的金鑰相同——完整檢查清單請參見 If the token request returns 401。
你只能終止屬於你所認證之應用程式的工作階段。由其他應用程式簽發的 jti 不會受到你的呼叫影響——你會收到一個成功回應且 wasActive: false,而該應用程式的工作階段會繼續執行。 狀態為 PERSONAL 的應用程式不支援 Basic 認證。

辨識工作階段

請提供「operator token 或其 jti」其中之一。至少需要一個。
傳入你交給 widget 的相同 patToken。它會以你的應用程式密鑰進行驗證,因此不屬於你的 token 會被直接拒絕。已過期的 token 仍會被接受——終止一個已過期的工作階段是無害的,而且代表你無需在呼叫前自行追蹤到期。token 自身的 exp 也會界定終止紀錄被保留的時長,這也是在你仍持有 token 時,這種作法較佳的原因。
同時提供兩者是允許的,只要它們描述的是同一個工作階段。以 token 為準,而 jti 會被視為對它的聲明——若 jti 與 token 內的值不一致,將被拒絕而非被靜默忽略,因此不會因混淆而終止錯誤的工作階段。

參數

  • input(TerminateWidgetSessionInput!):用於識別要終止的工作階段。

TerminateWidgetSessionInput 欄位

範例 mutation

cURL 範例

範例回應

回應欄位

wasActive: false 表示成功,非失敗。 這是使用者從未開啟 widget 時的正常回應——而這也是最安全的取消時機。終止一個從未被開啟的工作階段是完全支援的,也是你在已經交付付款但想取消時的建議作法。

何時會拒絕終止

終止操作具冪等性——對已被終止的工作階段再次終止也會成功。只有在以下兩種情況會被拒絕,且都代表與金流相關的問題已塵埃落定: 你可能看到的其他錯誤:

使用者會看到什麼

終止會在使用者於 widget 內的「下一次導覽或重新整理」時生效。它不會直接關閉已經渲染的畫面。 當他們下一次操作時,會看到一則「Session ended」訊息,指明你的應用程式並告知他們關閉視窗並從你的產品重新開始。若他們已進入付款確認步驟,該次確認會以相同訊息被拒絕,且伺服器端會以 WidgetSessionTerminated(WIDGET-005,410)拒絕該撥款。
僅執行終止本身「不會」停止已開始執行的撥款——此情況會回傳 409,你應等待完成或失敗事件,而不是假設金流已被攔停。

終止會被記住多久

被終止的工作階段,會在其原本仍可被使用的期間內被拒絕:
  • 以「token 終止」——直到該 token 自身的 exp,且至少為一小時。
  • 僅以「jti 終止」——為 30 天。operator token 的簽署時效並無上限,因此在沒有可讀取的 exp 時,會將終止紀錄保留遠超過任何可想見的工作階段壽命。
在此之後,紀錄會被丟棄。實務上 operator token 早已過期,因此無論如何該工作階段也無法再被使用。

後續步驟

設定你的伺服器

產生此 mutation 需要的 patToken 與 jti。

嵌入 widget

script 標籤、初始化呼叫、按鈕綁定。

嵌入式 Widgets 概觀

widget 工作階段、OAuth 授權與預先核准交易權杖如何協同運作。

冪等性

為什麼每個移動資金的呼叫都需要唯一的 jti。