已作廢購買通知讓您的 Google Play 伺服器在退款發生的當下立即撤銷存取權限

Google Play 上的退款不必是您日後在報表中才發現的事。無論買家是自助退款、由客服人員核准、由銀行強制發起退單,還是您自己在開啟撤銷旗標的情況下為訂單退款,Google Play 都能在購買被作廢的當下,將已作廢購買通知推送到您的伺服器。這則訊息極小,它指名確切的那筆購買,並且只帶著一條指令,收回權限,因為錢已經沒了。

已作廢購買通知究竟是什麼

已作廢購買通知是 Google Play 的 Real-time Developer Notifications(即 RTDN)其中一種類型。RTDN 是一個推送通道。Google 會將訊息發布到您擁有的 Cloud Pub/Sub 主題,而您的後端會在事件發生後片刻內收到它,而不是在下一次排定的輪詢時才得知。這正是已作廢購買通知相較於較舊的拉取路徑的全部重點:您在退款發生的當下就得知,而非數小時之後。

拉取路徑依然存在,也依然重要。Voided Purchases API 讓您的伺服器能依自己的排程,查詢某個時間範圍內被作廢的購買清單。兩者相輔相成。通知會在某筆購買狀態翻轉的當下告知您;API 則讓您能批次對帳,並補齊任何遺漏訊息可能留下的缺口。

它包裹在 Real-time Developer Notification 之中

已作廢購買通知從不單獨抵達。它位於一個 DeveloperNotification 外層封裝之中,而該封裝會以單一的 base64 編碼字串,放在 Pub/Sub 訊息的 data 欄位中送達。您的處理程式必須先將該字串解碼為 JSON,才能讀取任何內容。封裝一定會指名應用程式與事件時間,並且恰好包含 Google 所定義的五種通知物件中的一個。它們彼此互斥,因此攜帶 voidedPurchaseNotification 的訊息,不會同時攜帶訂閱或一次性事件。

它攜帶的四個欄位

剝去封裝後,已作廢購買通知本身就是四個欄位。這是刻意的精簡。Google 的立場是,如果您所需的只是找到正確的購買並調整權限,這四個欄位就足夠了,您無需回頭呼叫任何 API 就能採取行動。

productType 告訴您什麼被作廢了

productType 是一個很小的整數,它決定要採用您的哪一條撤銷路徑。訂閱作廢必須解除持續進行的存取;一次性購買作廢則只是移除單一權限。

refundType 告訴您退回了多少

refundType 將乾淨的全額撤回與部分撤回區分開來。部分退款的情況很狹窄。它只在一筆多數量的一次性購買,其數量被退了一部分但非全部時才出現。

先開啟它,否則它永遠不會抵達

已作廢購買通知預設不會流動。您只需在 Play Console 中啟用一次 RTDN,並將它指向由您掌控的 Pub/Sub 主題。這個開關位於 Monetize,接著是 Monetization setup,在頁面頂端的 Real-time developer notifications 區段中。勾選 Enable real-time notifications,然後以 projects/{project_id}/topics/{topic_name} 的格式貼上您完整的主題名稱,並在信任它之前使用 Send Test Message 來確認這條管道正常運作。

內容切換開關正是人們漏掉已作廢購買的地方。兩個選項都包含它們,因此您無法在保留訂閱的同時,不小心排除掉退款。

• 接收訂閱與所有已作廢購買的通知。您會收到訂閱事件和每一筆已作廢購買,但不包含一次性產品的購買事件。
• 接收訂閱與一次性產品的所有通知。您會收到上述內容,再加上一次性產品事件,例如 ONE_TIME_PRODUCT_PURCHASED 和 ONE_TIME_PRODUCT_CANCELED。

它讓您付出什麼代價,以金錢計

作廢是一筆在通知抵達您這裡時就已經記入的損失。銷售金額沒了,您為服務那位客戶所花的一切也沒了。如果他們生成了圖片、對您的模型發出呼叫、佔用了儲存空間,或觸發了對第三方的支付,這些成本都是用真金白銀付出的,不會隨退款一起回來。通知無法挽回這些之中的任何一項。它能做的,是從此刻起止血,而這正是要迅速處理它的全部原因。

在訂閱上出血最嚴重,在退單上出血也最嚴重。一筆您未能撤銷的訂閱,會為一位不再付費的客戶,月復一月地持續耗費您的服務成本。而退單是最昂貴的一種作廢。自 August 3, 2026 起,Google 的文件說明退單會將購買金額加上銀行手續費轉嫁給開發者。已作廢購買通知往往是您自己的系統最先聽聞退單已完成的地方,因此一個當場撤銷的處理程式,正是防止一筆流失的銷售,演變成一筆流失的銷售外加數週免費服務的關鍵。

如何處理已作廢購買通知,逐步說明

驗證訊息並去除重複

• 確認該 Pub/Sub 訊息來自 Google 並指向您所設定的主題,接著解碼 base64 的 data 欄位,以取得 DeveloperNotification 的 JSON。
• 使用 Pub/Sub 的 messageId 來丟棄重複項目。Google 警告同一則通知可能被傳遞不止一次,因此請將重送視為正常情況,並讓您的處理程式具備冪等性。
• 只在您已安全記錄訊息之後才確認它,如此一來處理程式中途當機也不會遺失該事件。

查找該筆購買

• 將 purchaseToken 與您首次授予權限時儲存的購買比對。以 orderId 作為支援查詢與人工對帳的備援。
• 讀取 productType 以選擇訂閱或一次性的撤銷路徑,並讀取 refundType 以在全額撤銷與部分撤銷之間做出決定。

撤銷並記錄

• 移除權限。對於全額退款,切斷對該商品的存取。對於基於數量的部分退款,將已授予的數量按退款的數量減少,其餘部分保持不變。
• 以 purchaseToken 和 orderId 為鍵,寫下您做了什麼以及在何時做的。這份紀錄能讓您日後回覆支援工單,也能讓 Voided Purchases API 與您自己的狀態乾淨地對帳。

它在其他退款訊號中的定位

已作廢購買通知是一則告知,而非一場協商。它告訴您一個已經定案的結果。值得把它與那些容易和它混淆的訊號放在一起看,因為只有其中一部分會徵詢您這一方的說法。

要牢記的原則很簡單。橫跨這兩家商店,開發者能發表意見的退款流程恰好只有兩種,Apple 的 CONSUMPTION_REQUEST 與 Google Play 的退單審查。已作廢購買通知兩者都不是。當它抵達您這裡時,決定早已成為過去,唯一還在您手中的,就是您撤銷的速度有多快。