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

認證

此 mutation 使用你的「應用程式」憑證進行認證,而不是使用者的 access token——與你用於 generateUserAccessTokenBasic 標頭相同:
從開發者主控台原樣送出 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 內的值不一致,將被拒絕而非被靜默忽略,因此不會因混淆而終止錯誤的工作階段。

參數

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

TerminateWidgetSessionInput 欄位

範例 mutation

cURL 範例

範例回應

回應欄位

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

何時會拒絕終止

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

使用者會看到什麼

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

終止會被記住多久

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

後續步驟

設定你的伺服器

產生此 mutation 需要的 patTokenjti

嵌入 widget

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

嵌入式 Widgets 概觀

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

冪等性

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