Google Play पर रिफंड चुपचाप आता है। चार्ज रिवर्स हो जाता है, ग्राहक ऐप का इस्तेमाल करता रहता है, और आपकी तरफ से तब तक कुछ नहीं बदलता जब तक आप जानबूझकर जांच न करें। जांच करना ही वह काम है जिसके लिए Voided Purchases API बना है। यह उन ऑर्डर को लौटाता है जो कैंसल, रिफंड या चार्जबैक किए गए थे, ताकि आप उस चीज़ का एक्सेस वापस ले सकें जिसके लिए ग्राहक ने अब पैसे देना बंद कर दिया है। इससे एक शेड्यूल्ड जॉब को वायर करें, जो वापस आए उसे पढ़ें, और entitlement को रिवोक करें। यही पूरा तंत्र है।
लगभग हर टीम एक चीज़ में उलझ जाती है, और यह कोड में नहीं बल्कि पॉलिसी में छिपी होती है। यह API सिर्फ उन्हीं ऑर्डर को सूचीबद्ध करता है जो वास्तव में रिवोक किए गए हों। Play Console में revoke ऑप्शन को टिक किए बिना कोई खरीद रिफंड करें, तो वह ऑर्डर यहां कभी नहीं दिखेगा, इसलिए आपकी जॉब बिल्कुल साफ चलती रहती है जबकि रिफंड पाया हुआ ग्राहक आपके बेचे हुए सब कुछ के साथ चला जाता है। आगे इस लेख में API की फील्ड-दर-फील्ड जानकारी, इसकी सीमाएं, और जब यह वायर्ड नहीं होता तो पैसा चुपचाप कहां बहता है, यह सब कवर किया गया है।
मुख्य बातें
Voided Purchases API, जिसे purchases.voidedpurchases.list मेथड के जरिए एक्सेस किया जाता है, उन ऑर्डर को सूचीबद्ध करता है जिन्हें Google Play ने कैंसल, रिफंड या चार्जबैक किया है, और यही वह चीज़ है जो आपको ऐसा सिस्टम बनाने देती है जो उन खरीद का एक्सेस हटा दे जो अब ग्राहक के पास नहीं हैं।
यह सिर्फ रिवोक किए गए ऑर्डर दिखाता है। बिना रिवोक किए जारी किया गया डेवलपर रिफंड यहां अदृश्य रहता है, इसलिए एक्सेस वापस लेने का मतलब है revoke ऑन करके रिफंड करना।
इसकी पहुंच रोलिंग 30 दिनों तक सीमित है। चूंकि startTime 30 दिन से पहले नहीं जा सकता, इसलिए अगर कोई सर्वर एक महीने से ज्यादा समय तक ऑफलाइन रहता है तो वे void हमेशा के लिए खो जाते हैं, यही वजह है कि पोलिंग को एक शेड्यूल पर चलाना जरूरी है।
voidedSource यह बताता है कि void किसने शुरू किया: 0 यूजर के लिए, 1 डेवलपर के लिए, 2 Google के लिए। voidedReason इसका कारण बताता है, जो 0 (Other) से शुरू होकर 7 (Chargeback) और 8 (Unacknowledged_purchase) तक जाता है।
रियल-टाइम डेवलपर नोटिफिकेशन किसी खरीद के void होते ही VoidedPurchaseNotification भेजते हैं, लेकिन इसे सिर्फ एक संकेत मानें। कुछ भी रिवोक करने से पहले Voided Purchases API से इसकी पुष्टि करें।
सब्सक्रिप्शन के रिन्यूअल को orderId से पहचानें, कभी purchaseToken से नहीं। एक ही purchaseToken किसी सब्सक्रिप्शन के हर रिन्यूअल में फैला होता है, इसलिए सिर्फ token से एक अवधि को दूसरी से अलग नहीं किया जा सकता।
अधिकतम सीमा है प्रतिदिन 6,000 क्वेरी और किसी भी 30-सेकंड के अंतराल में 30 क्वेरी, इसलिए हर रिक्वेस्ट को एक टाइम विंडो तक सीमित रखें और continuation token का इस्तेमाल करके पेज-दर-पेज आगे बढ़ें, कभी भी हर ऑर्डर के लिए अलग रिक्वेस्ट न भेजें।
API क्या जानकारी लौटाता है
यह एंडपॉइंट एक ही सवाल का जवाब देता है: इस ऐप के किन ऑर्डर को हाल ही में void किया गया है। एक void तीन नतीजों को समेटता है जो सभी ग्राहक का पैसा लौटाते हैं, यानी कैंसलेशन, रिफंड, या चार्जबैक। यह वन-टाइम in-app प्रोडक्ट्स और सब्सक्रिप्शन दोनों तक पहुंचता है, और एक पैरामीटर इसका दायरा तय करता है। type को डिफ़ॉल्ट 0 पर छोड़ें, तो सिर्फ voided in-app प्रोडक्ट purchases वापस आती हैं। type को 1 पर सेट करें तो आपको voided in-app purchases और voided subscription purchases दोनों एक साथ मिलती हैं।
रिस्पॉन्स में हर आइटम एक voided purchase ऑब्जेक्ट होता है जिसमें फील्ड्स का एक छोटा लेकिन महत्वपूर्ण सेट होता है:
orderId किसी एकल खरीद, किसी सब्सक्रिप्शन, या उसके भीतर किसी एक रिन्यूअल को यूनिक रूप से चिन्हित करता है। इसे अपनी join key मानें।
purchaseToken किसी वन-टाइम खरीद या सब्सक्रिप्शन की पहचान करता है, लेकिन यह रिन्यूअल को अलग नहीं करता, इसलिए इसके लिए orderId पर निर्भर रहें।
purchaseTimeMillis यह रिकॉर्ड करता है कि खरीद कब हुई, epoch से मिलीसेकंड में।
voidedTimeMillis यह रिकॉर्ड करता है कि इसे कब कैंसल, रिफंड या चार्जबैक किया गया, फिर से epoch से मिलीसेकंड में।
voidedSource यह बताता है कि void किसने शुरू किया, जहां 0 यूजर है, 1 डेवलपर है, और 2 Google है।
voidedReason कारण को 0 से 8 तक की एक इंटिजर वैल्यू के रूप में बताता है।
voidedQuantity किसी quantity-based partial refund से voided काउंट को दर्शाता है, और तभी दिखाई देता है जब includeQuantityBasedPartialRefund true हो।
क्योंकि एक purchaseToken पूरे सब्सक्रिप्शन को कवर करता है जबकि हर रिन्यूअल को एक नया orderId मिलता है, अगर आप अपने entitlements को token पर आधारित करेंगे तो आप गलत अवधि को रिवोक कर बैठेंगे। इसके बजाय orderId पर आधारित करें।
कुछ भी करने से पहले voidedReason पढ़ें
voidedReason ही वह चीज़ है जो एक साधारण सूची को एक वास्तविक फैसले में बदल देती है, क्योंकि एक change-of-mind रिफंड और एक बैंक चार्जबैक एक ही फीड में होते हैं फिर भी दोनों बिल्कुल अलग हैं। पूरी सूची इस प्रकार है:
1. Other को कोई निर्धारित श्रेणी नहीं दी गई है। इसे रिवोक करें और आगे बढ़ें।
2. Remorse का मतलब है ऐसा ग्राहक जिसने अपना मन बदल लिया, यह एक आम रिफंड है।
3. Not_received इस दावे को दर्शाता है कि प्रोडक्ट कभी पहुंचा ही नहीं, इस पर आपकी डिलीवरी की जांच करना उचित है।
4. Defective का मतलब है कि यह काम नहीं किया, यह एक क्वालिटी सिग्नल है जिसे आपको लॉग करना चाहिए।
5. Accidental_purchase एक अनजाने में की गई खरीद है, जो अक्सर किसी शेयर्ड डिवाइस पर होती है।
6. Fraud वह ट्रांजैक्शन है जिसे Google ने फ्रॉड के रूप में फ्लैग किया।
7. Friendly_fraud एक चार्जबैक है जिसमें असली कार्डधारक उस चार्ज को विवादित करता है जो उसने वास्तव में किया था।
8. Chargeback का मतलब है ग्राहक के बैंक द्वारा पेमेंट रिवर्स करना, जो बैंक के साथ फाइनल होता है और अब इसका बिल आपको दिया जाता है।
9. Unacknowledged_purchase तब होता है जब Google उस खरीद को ऑटो-रिफंड कर देता है जिसे आपके ऐप ने कभी acknowledge नहीं किया।
Reason 9 एक ऐसा रिफंड है जो आपने खुद बुलाया है। जिस भी खरीद को आपका ऐप acknowledge किए बिना छोड़ देता है, उसका पैसा Google द्वारा लौटा दिया जाता है, इसलिए इस फीड में unacknowledged_purchase असल में एक छूटी हुई कॉल की वजह से गंवाया गया रेवेन्यू है, न कि खरीदार की किसी पसंद की वजह से।
30-दिन की विंडो जो चुपचाप सूची को खाली करती जाती है
यह API पिछले 30 दिनों से आगे नहीं जाता। startTime डिफ़ॉल्ट रूप से अभी माइनस 30 दिन पर सेट होता है और इससे पहले सेट होने से इनकार कर देता है, और endTime डिफ़ॉल्ट रूप से वर्तमान समय पर सेट होता है, इसलिए आपको एक स्थायी आर्काइव की बजाय एक रोलिंग एक-महीने की विंडो मिलती है।
इसका असर बहुत स्पष्ट है। मान लीजिए कोई पोलिंग जॉब टूट जाए और पांच हफ्तों तक इस पर किसी का ध्यान न जाए, तो पहले हफ्ते के void पहले ही API से बाहर हो चुके होंगे, और कोई भी कॉल उन्हें वापस नहीं ला सकेगी। वे ऑर्डर अनरिवोक्ड रह जाते हैं, और अगर आपने उन्हें कहीं और कैप्चर नहीं किया होता तो आपको यह पता भी नहीं चलता कि वे हुए भी थे। इस नेट में ठीक उतना ही छेद है जितनी आपकी सबसे लंबी आउटेज। कम से कम रोज़ाना पोल करें और रियल-टाइम नोटिफिकेशन के साथ मिलान करें, 30 दिन को उसी सख्त डिलीशन क्लॉक की तरह मानें जो यह वास्तव में है।
ऑर्डर दिखेगा भी या नहीं, यह revoke पर निर्भर करता है
यही वह नंबर-वन वजह है जिसके चलते टीमें इस API को "खराब" कहती हैं। यह सिर्फ रिवोक किए गए ऑर्डर लौटाता है, और कुछ नहीं। यूजर द्वारा शुरू किए गए रिफंड, कैंसलेशन, चार्जबैक, और Google द्वारा शुरू किए गए रिफंड - ये सभी अपने आप रिवोक हो जाते हैं, इसलिए ये हमेशा फीड में आते हैं। डेवलपर द्वारा शुरू किया गया रिफंड इसका अपवाद है। चाहे आप Play Console से रिफंड जारी करें या Orders API के जरिए, revoke का चुनाव एक अलग फैसला बना रहता है जो आपको खुद करना होता है। अगर आप इसे न चुनें, तो ऑर्डर ग्राहक के साथ सेटल तो हो जाता है लेकिन इस फीड में कभी नहीं दिखता।
बात संक्षेप में यह है। जब आपका लक्ष्य एक्सेस काटना हो, तो revoke ऑन करके रिफंड करें। इसे छोड़ देने पर आप पैसा तो लौटा चुके होते हैं लेकिन दरवाजा खुला छोड़ देते हैं, और आपकी रिवोकेशन जॉब, चाहे कितनी भी सावधानी से बनाई गई हो, उसके पास काम करने के लिए कुछ नहीं बचता।
क्वोटा से टकराए बिना इसे पोल करना
यह एंडपॉइंट rate limited है, और इसकी सीमाएं इतनी कम हैं कि कोई लापरवाह लूप आसानी से इन्हें पार कर सकता है। आपको प्रतिदिन 6,000 क्वेरी मिलती हैं, जिन्हें Pacific Time में गिना जाता है, और किसी भी 30-सेकंड के अंतराल में 30 से ज्यादा नहीं। यह बजट windowed पोलिंग के लिए उपयुक्त है और हर ऑर्डर के लिए अलग कॉल वाले किसी भी डिज़ाइन को दंडित करता है।
टाइम विंडो और continuation token
maxResults डिफ़ॉल्ट रूप से 1,000 पर सेट होता है, और यह अधिकतम सीमा भी है। अगर किसी विंडो में एक पेज की क्षमता से ज्यादा void हों, तो रिस्पॉन्स में एक tokenPagination ऑब्जेक्ट आता है जिसमें एक nextPageToken होता है। पेजों में आगे बढ़ने के लिए अपनी अगली कॉल में वह token भेजें। startTime और endTime से विंडो की सीमाएं तय करें, token खत्म होने तक पेजिंग करते रहें, और तभी विंडो को आगे बढ़ाएं। यह क्रम 30-सेकंड की बर्स्ट सीमा और दैनिक सीमा, दोनों से बचा रहता है।
रियल-टाइम नोटिफिकेशन रोज़ाना के अंतर को पाटते हैं
रोज़ाना की पोलिंग भी आपको 24 घंटे तक अंधेरे में रख सकती है, और लंबे गैप को ही 30-दिन की विंडो दंडित करती है। रियल-टाइम डेवलपर नोटिफिकेशन इस देरी को खत्म करते हैं। किसी खरीद के void होते ही, एक VoidedPurchaseNotification आपके नियंत्रण में मौजूद एक Cloud Pub/Sub टॉपिक पर पब्लिश हो जाता है, और आपका बैकएंड इसे कुछ ही सेकंड में प्राप्त कर लेता है। इसका पेलोड बेहद संक्षिप्त होता है:
purchaseToken मूल खरीद का token है।
orderId voided ट्रांजैक्शन की id है, जो हर सब्सक्रिप्शन रिन्यूअल के लिए नई बनती है।
productType सब्सक्रिप्शन के लिए 1 और वन-टाइम खरीद के लिए 2 होता है।
refundType पूरे रिफंड, जिसे 1 चिन्हित किया गया है, को quantity-based partial refund से अलग करता है, जिसे 2 चिन्हित किया गया है।
नोटिफिकेशन को एक अटल सत्य नहीं बल्कि एक अलर्ट मानें। जैसे ही कोई VoidedPurchaseNotification आए, Voided Purchases API से यह वेरिफाई करें कि ऑर्डर वास्तव में किस स्थिति में है, और तभी रिवोक करें। अलर्ट आपको जांच करने के लिए कहता है; API आपको सच बताता है।
इसकी वित्तीय कीमत क्या है
यह API महज एक बुनियादी ढांचा है, लेकिन इसे बिछाने की वजह एक बिल है, और इस पर मौजूद दो आंकड़े बढ़ते जा रहे हैं।
3 अगस्त, 2026 से, चार्जबैक का बिल आपका होगा
3 अगस्त, 2026 से, Google चार्जबैक की लागत को डेवलपर पर डाल देगा। आप खरीद की कीमत गंवाते हैं और उसके ऊपर बैंक की चार्जबैक फीस भी चुकाते हैं। voidedReason का 7 अब सिर्फ एक गंवाई हुई बिक्री नहीं रह जाता, बल्कि एक फीस के साथ जुड़ा हुआ लाइन आइटम बन जाता है। चार्जबैक को खुद रिवर्स नहीं किया जा सकता, क्योंकि यह बैंक के साथ फाइनल होता है, लेकिन void को जल्दी पकड़ लेने से आप entitlement को रिवोक कर सकते हैं और, जो कुछ भी अभी भी डिलीवर किया जा रहा है उसके लिए, ऐसे ग्राहक पर खर्च करना बंद कर सकते हैं जिसे रिफंड मिला और फिर रिवर्स भी हुआ।
आप उस ग्राहक को फंड करते रहते हैं जिसे पहले ही रिफंड मिल चुका है
जैसे ही कोई void आता है, बिक्री की कीमत खत्म हो जाती है। जो चीज़ अब भी आपके नियंत्रण में है, वह है डिलीवरी जारी रखने का खर्च। जब तक कोई रिफंड पाया हुआ entitlement सक्रिय रहता है, उतने हर घंटे के लिए वे बिल आपकी तरफ आते रहते हैं जिन्हें ग्राहक अब कवर नहीं करता: कंप्यूट, मॉडल प्रोवाइडर कॉल्स, स्टोरेज, और उनकी गतिविधि से ट्रिगर होने वाला कोई भी क्रिएटर या पार्टनर पेआउट। इस API पर रिवोकेशन पाइपलाइन बनाना ही वह तरीका है जिससे यह खर्च रोका जाता है। इसे छोड़ने का मतलब है कि आप उन लोगों के लिए प्रोडक्ट को फंड कर रहे हैं जिन्हें स्टोर पहले ही रिफंड दे चुका है।
Friendly fraud एक ट्रेंड है, कोई एक घटना नहीं
voidedReason का 5 या 6 शायद ही कभी अकेले होता है। Fraud और friendly fraud अकाउंट्स, डिवाइसेज़ और कभी-कभी खास प्रमोशन के इर्द-गिर्द क्लस्टर बनाते हैं। चूंकि यह API हर void के साथ voidedSource और voidedReason जोड़ता है, इसलिए आपके पास हर रिवर्सल को अलग-थलग नुकसान मानने की बजाय प्रति अकाउंट abuse को ट्रैक करने के लिए पर्याप्त जानकारी होती है। जो अकाउंट दूसरी बार चार्जबैक करता है, वह आपको वह बता रहा है जो पहला रिफंड नहीं बता पाया।
सब कुछ मिलाकर
एक बार सभी हिस्से हाथ में आ जाएं, तो पूरा मॉडल काफी छोटा हो जाता है। VoidedPurchaseNotification को रियल टाइम में सुनें ताकि कुछ भी एक पूरा दिन इंतज़ार न करे। Voided Purchases API को सच का स्रोत मानें, orderId पर आधारित, ताकि रिन्यूअल कभी आपस में न घुलें-मिलें। voidedSource और voidedReason पढ़ें ताकि चार्जबैक को remorse रिफंड से अलग तरीके से हैंडल किया जाए। इतनी टाइट कैडेंस पर पोल करें कि 30-दिन की विंडो कभी नुकसान न पहुंचाए, और जब भी आपका इरादा एक्सेस काटना हो, revoke ऑन करके रिफंड करें।
यही वह लेयर है जिसे Refund Sensor आपकी ओर से चलाता है। यह रियल-टाइम नोटिफिकेशन को प्राप्त करता है, हर void का API से मिलान करता है, पूरे प्रोडक्ट की बजाय सटीक ऑर्डर को रिवोक करता है, और बैंक चार्जबैक को सामान्य रिफंड से अलग रखता है ताकि महंगे मामले छिपने की बजाय सामने आएं। आपको कुछ ही सेकंड में एक्सेस वापस मिल जाता है और यह पूरा रिकॉर्ड मिलता है कि किसने, क्या, और क्यों void किया, बिना किसी Pub/Sub पाइपलाइन या पोलिंग जॉब को खुद बनाए।
इन नियमों का दस्तावेज़ीकरण कहां है
अक्सर पूछे जाने वाले प्रश्न
क्योंकि फीड में सिर्फ रिवोक किए गए ऑर्डर होते हैं। यूजर द्वारा शुरू किए गए रिफंड, कैंसलेशन, चार्जबैक, और Google द्वारा शुरू किए गए रिफंड - ये सभी अपने आप रिवोक हो जाते हैं और हमेशा दिखते हैं। आप खुद जो रिफंड जारी करते हैं, वह तभी दिखेगा जब आपने उसे रिवोक करना भी चुना हो। रिवोक किए बिना रिफंड करने पर ऑर्डर सेटल तो हो जाता है लेकिन यहां दिखाई नहीं देता, इसलिए जब भी आपका मकसद एक्सेस वापस लेना हो, revoke को ऑन करें।
सिर्फ तीस दिन, इससे आगे नहीं। startTime डिफ़ॉल्ट रूप से मौजूदा समय माइनस 30 दिन पर सेट होता है और इससे पहले की किसी भी वैल्यू को स्वीकार नहीं करता, इसलिए यह एंडपॉइंट किसी आर्काइव की बजाय एक रोलिंग एक-महीने की विंडो की तरह काम करता है। जैसे ही कोई void 30 दिन से पुराना हो जाता है, वह हमेशा के लिए चला जाता है और उसे वापस लाने का कोई तरीका नहीं होता, यही वजह है कि आपको एक शेड्यूल पर पोल करना चाहिए और इसे रियल-टाइम नोटिफिकेशन से बैकअप देना चाहिए।
दोनों की अपनी भूमिका है। VoidedPurchaseNotification कुछ ही सेकंड में आप तक पहुंच जाता है और आपको जांच करने के लिए कहता है, लेकिन Google का मार्गदर्शन इसे सच नहीं बल्कि एक संकेत मानने का है। Voided Purchases API के जरिए मौजूदा स्थिति की पुष्टि करें, फिर रिवोक करें। नोटिफिकेशन देरी को खत्म करता है; API वह अधिकृत voidedSource और voidedReason देता है जिस पर आप वास्तव में कार्रवाई करते हैं।
voidedReason को देखें। 7 का मतलब चार्जबैक है, जहां ग्राहक के बैंक ने पेमेंट रिवर्स किया है, और 6 का मतलब friendly fraud है। 1 एक सामान्य change-of-mind रिफंड है। यह अंतर इसलिए मायने रखता है क्योंकि 3 अगस्त, 2026 से, Google चार्जबैक की कीमत और बैंक फीस डेवलपर पर डाल देगा, इसलिए 7 आपको एक सामान्य रिफंड से ज्यादा महंगा पड़ता है।
हां, शामिल हैं। type पैरामीटर को 1 पर सेट करें और आपको voided in-app purchases के साथ-साथ voided subscription purchases भी मिलेंगी; डिफ़ॉल्ट वैल्यू 0 सिर्फ in-app प्रोडक्ट्स लौटाती है। सब्सक्रिप्शन के लिए, सही voided अवधि का पता orderId से लगाएं, क्योंकि एक ही purchaseToken हर रिन्यूअल में फैला होता है जबकि हर रिन्यूअल ट्रांजैक्शन को अपना अलग orderId मिलता है।
