भुगतान की प्रामाणिक सूचना से भी एक ही ऑर्डर दो बार पूरा नहीं होना चाहिए। क्रिप्टो भुगतान Webhook के लिए दो अलग सुरक्षा उपाय चाहिए: पहले जांचें कि घटना किसने भेजी, फिर सुनिश्चित करें कि दोबारा प्रसंस्करण से व्यावसायिक कार्रवाई दोहराई न जाए। हस्ताक्षर पहले प्रश्न का उत्तर देता है। इडेम्पोटेंसी, यानी दोहराने पर भी परिणाम न बदलना, दूसरे का।
यह मार्गदर्शिका उन डेवलपर के लिए है जो एकमुश्त डिजिटल खरीद, लाइसेंस या खाते में राशि जोड़ने की सुविधा को Yolfi से जोड़ रहे हैं। इसमें Yolfi का मूल Webhook प्रारूप और अनुप्रयोग के लिए सुझाई गई संरचना समझाई गई है, न कि खरीद पूरी करने की कोई तैयार सेवा। सदस्यताओं में पहुंच सदस्यता के जीवनचक्र पर भी निर्भर करती है; हर नवीनीकरण पर एकमुश्त ऑर्डर वाला नियम न लगाएं।
प्रामाणिक Webhook से भी कार्रवाई दोबारा क्यों हो सकती है
प्राप्तकर्ता घटना को सफलतापूर्वक सहेज सकता है, लेकिन उसका HTTP उत्तर रास्ते में खो सकता है। तब भेजने वाला फिर प्रयास करता है। पृष्ठभूमि प्रक्रिया भी पहुंच देने के बाद, लेकिन काम पूरा होने का रिकॉर्ड लिखने से पहले बंद हो सकती है। इनमें से किसी भी स्थिति का मतलब यह नहीं कि ग्राहक ने दूसरा भुगतान किया है।
Yolfi के Webhook घटना संदर्भ में कम से कम एक बार सूचना पहुंचाने और कई प्राप्ति बिंदुओं के लिए स्वतंत्र पुनःप्रयासों का उल्लेख है। प्रणाली इस तरह बनाएं कि वही घटना फिर आ सके, संभवतः पहली सूचना का प्रसंस्करण चलते समय भी। पुनःप्रयासों की किसी खास समय-सारणी पर निर्भर न रहें और यह न मानें कि सूचनाएं हमेशा बनने के क्रम में ही पहुंचेंगी।
तीन तरह की पहचान अलग रखें:
| पहचान | यह किसे पहचानती है | सुझाया गया नियंत्रण |
|---|---|---|
हस्ताक्षरित घटना का id |
सेवा प्रदाता की एक घटना, उसकी दोहराई गई सूचनाओं सहित | प्रदाता, संगठन और परिवेश के दायरे में घटना का अद्वितीय रिकॉर्ड |
| चालान या भुगतान का संदर्भ | भुगतान का एक प्रयास | संबंधित व्यावसायिक ऑर्डर से सहेजा गया संबंध |
| व्यावसायिक ऑर्डर का संदर्भ | ग्राहक को क्या मिलना चाहिए | उस ऑर्डर को पूरा करने की अद्वितीय कार्रवाई |
केवल दोहराई गई घटनाओं को पहचानना पर्याप्त नहीं है: एक ऑर्डर के दो सफल भुगतान प्रयासों के घटना पहचानकर्ता अलग हो सकते हैं। ऑर्डर स्तर की सुरक्षा दूसरा लाइसेंस देने या खाते में दोबारा राशि जोड़ने से रोकती है, जबकि अतिरिक्त प्राप्त राशि की अलग से जांच होती है।
अनुरोध के क्षेत्रों पर भरोसा करने से पहले उसका मूल रूप जांचें
Yolfi के हस्ताक्षर संबंधी मौजूदा निर्देशों का पालन करें। मूल प्रारूप के अनुरोध X-Yolfi-Signature का उपयोग करते हैं। यह उस प्राप्ति बिंदु के हस्ताक्षर रहस्य से अनुरोध के मूल मुख्य भाग पर गणना किया गया HMAC-SHA256 है, जिसे Base64 में कूटबद्ध किया जाता है। संगठन की API कुंजी Webhook का रहस्य नहीं है।
JSON मध्यवर्ती सॉफ़्टवेयर के बदलने से पहले मूल मुख्य भाग सुरक्षित कर लें। हस्ताक्षर की गणना करें और स्थिर समय लेने वाले तुलना फ़ंक्शन से मिलाएं; हस्ताक्षर गायब या गलत प्रारूप में हो तो कोई व्यावसायिक कार्रवाई किए बिना अनुरोध अस्वीकार करें। हस्ताक्षर रहस्य सुरक्षित रहस्य-भंडार या संरक्षित परिवेश विन्यास में रखें, स्रोत फ़ाइलों या सहायता संबंधी लॉग में कभी नहीं।
सत्यापन के बाद ही सामग्री पढ़ें और उसके क्षेत्रों की वैधता जांचें। दोहराव पहचानने के लिए हस्ताक्षरित सामग्री का id इस्तेमाल करें। X-Yolfi-Event-ID सुविधा के लिए दी गई प्रति है, अलग से हस्ताक्षरित मान नहीं; इसका उपयोग करें तो इसे सामग्री के पहचानकर्ता के बराबर होना अनिवार्य करें। प्राप्ति बिंदु को उसके अपेक्षित संगठन से बांधें और orgId मौजूद हो तो जांचें। उपयोगकर्ता द्वारा दिया गया अतिरिक्त विवरण यह तय न करे कि किस संगठन के डेटा तक पहुंच की अनुमति है।
मान्य हस्ताक्षर पुरानी सूचना को नई नहीं बनाता। संसाधित घटनाओं के पहचानकर्ता सहेजना अब भी जरूरी है। दस्तावेज़ में वर्णित Yolfi हस्ताक्षर समय-मुद्रा के आधार पर ताजगी की जांच नहीं करता, इसलिए यह दावा न करें कि केवल HMAC सत्यापन ही अनुरोध को दोबारा चलाने से रोकता है।
पहले सहेजें, फिर प्राप्ति स्वीकार करें और काम असमकालिक रूप से करें
टिकाऊ आगत भंडार इस्तेमाल करें: अनुप्रयोग की ऐसी तालिका जो प्रामाणिकता जांच चुकी घटना और उसके प्रसंस्करण की स्थिति दर्ज करे। डेटाबेस के अद्वितीयता प्रतिबंध के तहत घटना जोड़ें; पहले अलग से “क्या यह मौजूद है?” जांचकर फिर बिना सुरक्षा के रिकॉर्ड न जोड़ें। एक साथ आए दोनों अनुरोध उस जांच से गुजर सकते हैं।
टिकाऊ रूप से स्वीकार करने के तुरंत बाद 200 OK लौटाएं, तब भी जब प्रामाणिक दोहराव पहले से सहेजा हो। सहेजना विफल हो तो घटना की स्वीकृति न दें। तुरंत उत्तर देकर फिर केवल अस्थायी स्मृति में काम चलाना टिकाऊ व्यवस्था नहीं है: पुनःआरंभ से अनुप्रयोग के पास मौजूद एकमात्र प्रति खो सकती है।
इसके बाद पृष्ठभूमि प्रक्रिया सहेजी गई घटना पढ़ सकती है, ऑर्डर से उसका संबंध जांच सकती है और व्यावसायिक स्थिति बदल सकती है। विफल काम दिखाई देता रहे: पुनःप्रयासों की गिनती, अगला कदम और चेतावनी के जिम्मेदार व्यक्ति का विवरण रखें। सीमित पहुंच वाले भंडार में केवल जरूरी सामग्री रखें; घटना के मुख्य भाग में ग्राहक की जानकारी हो सकती है।
पुष्टि और सही ऑर्डर की जांच के बाद ही खरीद पूरी करें
Yolfi की Webhook मार्गदर्शिका में payment.confirmed को ऑर्डर पूरा करने का मुख्य संकेत बताया गया है। invoice.created का मतलब चालान बनना है, ग्राहक का भुगतान करना नहीं। ब्राउज़र का दूसरे पेज पर जाना या स्क्रीनशॉट, सर्वर पर सत्यापित पुष्टि की जगह नहीं ले सकता।
घटना को सर्वर पर सहेजे गए ऑर्डर से जोड़ें। मूल प्रक्रिया में स्वतंत्र API Checkout घटनाओं में checkoutSessionId और merchantOrderId हो सकते हैं, जबकि paylinkId न हो। केवल Paylink पहचानकर्ता न होने पर किसी वैध स्वतंत्र खरीद को अस्वीकार न करें। उसी तरह, दोबारा उपयोग किए जा सकने वाले Paylink का पहचानकर्ता अकेले किसी खरीदार के ऑर्डर की अद्वितीय पहचान नहीं करता।
खरीद देने से पहले अपेक्षित संगठन, परिवेश, भुगतान प्रयास और व्यावसायिक राशि का संदर्भ जांचें। दस्तावेज़ में दिया amount भुगतान वाले टोकन में विक्रेता को मिलने वाली अंतिम राशि है; यह अपने आप स्थानीय मुद्रा में मूल चालान की कुल राशि नहीं है। इन दो संख्याओं की तुलना ऐसे न करें मानो दोनों की इकाई समान हो। सर्वर से स्वीकृत मूल ऑर्डर और उसकी कीमत तय करने का संदर्भ सुरक्षित रखें।
बदलते विवरण वाली खरीद के लिए API Checkout प्रक्रिया अपनाएं, ताकि ऑर्डर और सत्र का संबंध सुरक्षित रहे। तय उत्पादों के लिए भुगतान लिंक बार-बार इस्तेमाल किया जा सकने वाला भुगतान प्रवेश बिंदु देते हैं; खरीद देने का निर्णय फिर भी आपके अनुप्रयोग का है।
केवल घटना तालिका नहीं, कार्रवाई के असर को भी सुरक्षित करें
अगर ऑर्डर पूरी तरह आपके डेटाबेस के भीतर पूरा होता है, तो घटना का परिणाम और ऑर्डर की स्थिति में बदलाव एक ही डेटाबेस लेनदेन में दर्ज करें। व्यावसायिक कार्रवाई को अद्वितीय बनाएं, जैसे एकमुश्त ऑर्डर पर पहुंच का अधिकार केवल एक बार देना। दोहराई गई घटना मौजूदा परिणाम लौटाए, नया अधिकार न दे।
अगर खरीद पूरी करने के लिए दूसरी सेवा को बुलाना पड़ता है, तो टिकाऊ निर्गत भंडार इस्तेमाल करें: ऑर्डर की स्थिति बदलते समय इच्छित कार्रवाई भी सहेजें, फिर पृष्ठभूमि प्रक्रिया उसे भेजे। प्राप्तकर्ता समर्थन देता हो तो आगे की कार्रवाई के लिए ऑर्डर पर आधारित स्थिर इडेम्पोटेंसी कुंजी दें। केवल निर्गत भंडार दूरस्थ कार्रवाई का दोहराव नहीं रोकता, यदि कार्रवाई सफल होने के बाद प्रक्रिया बंद हो जाए।
यदि गंतव्य इडेम्पोटेंसी या परिणाम की खोज का समर्थन नहीं करता, तो अपरिवर्तनीय कार्रवाई को बिना जांच दोहराने के बजाय अनिश्चित परिणाम को मिलान के लिए छोड़ें। HTTP Webhook हर डेटाबेस, कतार और बाहरी सेवा में “ठीक एक बार” होने का वादा नहीं कर सकता।
पुरानी घटनाओं को पूरे हो चुके ऑर्डर की स्थिति पीछे ले जाने से रोकें। invoice.overdue घटना एक प्रयास से जुड़ी है और उसे पूरे हो चुके ऑर्डर का परिणाम नहीं मिटाना चाहिए। नियमित पहुंच के लिए प्रदाता चालान की घटनाओं को subscription.overdue और subscription.cancelled से अलग रखता है; दस्तावेज़ में दी सदस्यता नीति अलग से लागू करें।
वास्तविक ऑर्डर लेने से पहले विफलता की स्थितियां जांचें
प्राप्तकर्ता और पृष्ठभूमि प्रक्रिया के स्वीकृति परीक्षण में ये स्थितियां शामिल करें:
- एक ही हस्ताक्षरित घटना दो बार और एक साथ भेजें: घटना का एक रिकॉर्ड और एक व्यावसायिक असर हो।
- ऑर्डर की स्थिति बदलने से पहले और बाद में प्रक्रिया रोकें: दोबारा चालू होने पर पहुंच दूसरी बार न मिले।
- एक ऑर्डर के दो पुष्ट भुगतान प्रयास भेजें: ऑर्डर एक बार पूरा हो और अतिरिक्त प्राप्त राशि चिह्नित हो।
- अमान्य हस्ताक्षर, मेल न खाने वाला संगठन और अज्ञात ऑर्डर भेजें: खरीद पूरी न हो।
- पुष्टि के बाद चालान की पुरानी घटना भेजें: पूरी हो चुकी खरीद की स्थिति पीछे न जाए।
- वास्तविक भुगतान वाले प्राप्तकर्ता को परीक्षण घटना भेजें: कोई वास्तविक लाइसेंस, माल की भेजाई या खाते में राशि न दी जाए।
Yolfi के नियंत्रण पटल की परीक्षण घटनाएं livemode: false और evt_test_ से शुरू होने वाले पहचानकर्ता का उपयोग करती हैं। वे सूचना की डिलीवरी और सामग्री का प्रसंस्करण जांचती हैं, लेकिन वास्तविक भुगतान रिकॉर्ड नहीं बनातीं। परीक्षण और वास्तविक कार्रवाइयों को स्पष्ट रूप से अलग रखें; सफल परीक्षण सूचना इस बात का प्रमाण नहीं है कि खरीद का भुगतान निपट चुका है।
प्रामाणिकता जांच के बाद प्रसंस्करण की प्रतीक्षा करती घटनाओं, पृष्ठभूमि प्रक्रियाओं की विफलताओं और खरीद पूरी होने के परिणाम के बिना मौजूद पुष्ट भुगतानों पर नजर रखें। इन अपवादों को भुगतान मिलान की जांच-सूची से जोड़ें। दूसरी प्राप्त राशि सच में अतिरिक्त भुगतान हो, केवल दोहराई गई सूचना नहीं, तो प्रमाण मिटाने के बजाय धनवापसी की समीक्षा प्रक्रिया अपनाएं।
अक्सर पूछे जाने वाले प्रश्न
क्या हस्ताक्षर सत्यापन खाते में दोबारा राशि जुड़ने से रोकता है?
नहीं। यह प्रामाणिकता और अखंडता की जांच करता है। प्रामाणिक घटना एक से अधिक बार आ सकती है और पहले मान्य रहा अनुरोध दोबारा चलाया जा सकता है। घटना पहचानकर्ता सहेजें और ऑर्डर स्तर का व्यावसायिक प्रतिबंध लागू करें।
क्या घटना सहेजने से पहले सफलता का उत्तर देना चाहिए?
नहीं। टिकाऊ रूप से स्वीकार करने के बाद प्राप्ति की पुष्टि करें, फिर धीमा काम असमकालिक रूप से करें। वरना उत्तर देने के बाद हुई विफलता से घटना बिना पता चले खो सकती है।
क्या लेनदेन का हैश दोहराव पहचानने की पर्याप्त कुंजी है?
Webhook प्रसंस्करण के लिए नहीं। घटना की डिलीवरी के लिए दस्तावेज़ में दिया हस्ताक्षरित घटना पहचानकर्ता और खरीद पूरी करने के लिए अपनी ऑर्डर कुंजी इस्तेमाल करें। हस्तांतरण और ऑर्डर की पहचान अलग होती है; एक लेनदेन में कई हस्तांतरण हो सकते हैं।
क्या एडेप्टर की सामग्री के लिए वही प्रसंस्करण प्रक्रिया इस्तेमाल कर सकते हैं?
उनके डेटा अनुबंध की जांच किए बिना नहीं। यह लेख NONE एडेप्टर वाले मूल प्रारूप का वर्णन करता है। अन्य प्रदाताओं से संगत एडेप्टर की सामग्री का ढांचा अलग हो सकता है; मूल प्रारूप को पढ़ने और संबंध जोड़ने के नियम दोबारा इस्तेमाल करने से पहले उनके दस्तावेज़ में दिए क्षेत्र जांचें।
निष्कर्ष: पुष्टि करें, सहेजें और केवल एक बार पूरा करें
भरोसेमंद क्रिप्टो भुगतान स्वचालन प्रामाणिक सूचना की डिलीवरी को ऑर्डर के व्यावसायिक असर से अलग रखता है। मूल सामग्री के हस्ताक्षर जांचें, घटना सहेजें, ऑर्डर से मिलाएं और पुनःप्रयासों में खरीद पूरी करना सुरक्षित बनाएं। तय उत्पादों के लिए Yolfi भुगतान लिंक या बदलते विवरण वाले ऑर्डर के लिए दस्तावेज़ में बताए सर्वर-निर्मित सत्र से शुरुआत करें, और हर खरीद केवल एक बार देने की जिम्मेदारी अनुप्रयोग के पास रखें।
