पेमेंट इंटीग्रेशन रिलीज़: API, वेबहुक और फ़ाइनेंशियल रिपोर्ट

फ़ाइनेंस टीम के एक कर्मचारी ने एक्सपोर्ट फ़ाइल में एक उपयोगी कॉलम जोड़ दिया। अगली सुबह ऑटोमैटिक रिकंसिलिएशन ने कमीशन को अमाउंट वाले फ़ील्ड में दर्ज कर दिया। पेमेंट API में किसी ने कुछ नहीं बदला था, वेबसाइट का कोई रिलीज़ भी नहीं हुआ था, फिर भी पैसे से जुड़ी प्रक्रिया बदल चुकी थी। API वर्ज़निंग पर बात शुरू करने के लिए यह अच्छा उदाहरण है: इंटीग्रेशन का कॉन्ट्रैक्ट पेमेंट रिक्वेस्ट के एंडपॉइंट से कहीं ज़्यादा बड़ा होता है।

बदलाव SDK, API वर्ज़न, नोटिफ़िकेशन के फ़ॉर्मैट, अकाउंट सेटिंग्स, रिपोर्ट की संरचना और स्टेटस की आपकी अपनी व्याख्या, सब पर असर डाल सकता है। अगर टीम सिर्फ़ ऐप्लिकेशन कोड पर नियंत्रण रखती है, तो कुछ रिलीज़ उसकी जानकारी के बिना ही हो जाते हैं। नीचे एक ऐसी प्रक्रिया दी गई है जो इन बदलावों को दिखने लायक और जाँचने लायक बनाती है।

डेटा से जुड़े चार कॉन्ट्रैक्ट

पहला कॉन्ट्रैक्ट: ऐप्लिकेशन पेमेंट प्रोवाइडर को क्या भेजता है और कौन-सा जवाब समझता है। दूसरा: वह कौन-से एसिंक्रोनस इवेंट स्वीकार करता है और उनकी प्रामाणिकता कैसे जाँचता है। तीसरा: रिपोर्ट में कौन-से फ़ाइनेंशियल रिकॉर्ड मिलते हैं। चौथा: आपका अपना प्रोडक्ट इन जानकारियों के आधार पर किसे नतीजा मानता है। एक कॉन्ट्रैक्ट बदलने से बाक़ी तकनीकी रूप से न टूटें, फिर भी उनका मतलब बदल सकता है।

Stripe API रिक्वेस्ट के लिए वर्ज़न तय करने देता है और webhook endpoint का वर्ज़न अलग से रखता है। Stripe के वर्ज़निंग नियम। इसलिए «SDK अपडेट हो गया» वाली एक लाइन यह साबित नहीं करती कि हर कंज़्यूमर को अपेक्षित संरचना मिल रही है। सिर्फ़ रिपॉज़िटरी में डिपेंडेंसी के वर्ज़न नहीं, बल्कि हर चैनल का असल में लागू कॉन्फ़िगरेशन दर्ज करें।

Adyen कम्पैटिबल बदलावों और नए API वर्ज़न की ज़रूरत वाले बदलावों में फ़र्क़ करता है; लाइब्रेरी के वर्ज़न की अपनी अलग स्कीम है। Adyen के नियम। सटीक कॉन्ट्रैक्ट सप्लायर के दस्तावेज़ों में ही पढ़ना चाहिए। एक अनुमत नया फ़ील्ड जुड़ना और किसी मौजूदा फ़ील्ड का मान बदलना, आपके हैंडलर के लिए अलग-अलग नतीजे लाते हैं।

नया अनजाना मान दिखना चाहिए

एक ट्रेनिंग सिस्टम में parser तीन स्टेटस समझता है। तभी चौथा स्टेटस आ जाता है। एक ख़तरनाक विकल्प है उसे सफल मान लेना, ताकि प्रक्रिया न रुके। दूसरा ख़तरनाक विकल्प है उस पंक्ति को छोड़ देना और फ़ाइनेंस टीम को «साफ़» रिपोर्ट थमा देना। हमारी सुझाई गई नीति यह है कि रिकॉर्ड को अनुमत दायरे में सहेजें, असमर्थित मान को चिह्नित करें और बिना किसी ऑटोमैटिक फ़ाइनेंशियल असर के उसे जाँच के लिए भेज दें।

किसी वैकल्पिक अनजाने फ़ील्ड के लिए व्यवहार अलग हो सकता है: अगर यह दस्तावेज़ में लिखे कॉन्ट्रैक्ट के अनुरूप है, तो उसे सही तरीके से नज़रअंदाज़ किया जा सकता है। इसलिए «हर नए फ़ील्ड पर फ़ेल हो जाओ» वाला नियम भी बहुत मोटा है। संरचना के विस्तार, अनजाने बिज़नेस स्टेटस, अनिवार्य फ़ील्ड के न होने और अमाउंट के फ़ॉर्मैट में बदलाव को अलग-अलग पहचानें। हर एक के लिए अलग टेस्ट चाहिए।

फ़ाइनेंशियल CSV भी एक API है

Adyen साफ़ चेतावनी देता है कि रिपोर्ट के कॉलम की संरचना और क्रम बदलने से ऑटोमैटिक प्रोसेसिंग प्रभावित हो सकती है। Payment accounting report के कॉलम की सेटिंग। ऐसी सेटिंग्स को नियंत्रित इंटीग्रेशन का हिस्सा मानें, भले ही उन्हें डैशबोर्ड में माउस से बदला जाता हो।

पार्सर के लिए बेहतर है कि वह «अमाउंट हमेशा आठवें कॉलम में होता है» पर भरोसा करने के बजाय अपेक्षित हेडर और अनिवार्य फ़ील्ड जाँचे। इसके अलावा करेंसी, चिह्न (प्लस/माइनस), स्केल, रिकॉर्ड की संख्या और जहाँ उपलब्ध हों वहाँ चेकसम भी जाँचें। सही हेडर फ़ील्ड का मतलब बदलने से नहीं बचाता, इसलिए अनुमत टेस्ट सेट में असली रिकॉर्ड टाइप के उदाहरण होने चाहिए।

रिपोर्ट के मालिक को पता होना चाहिए कि कौन-से सिस्टम उसे पढ़ते हैं। बदलाव से पहले एक सैंपल तैयार करें, कंज़्यूमर सिस्टम जाँचें और स्विच का समय तय करें। अगर प्रोडक्ट सपोर्ट करता है, तो पुराना कॉन्फ़िगरेशन सुरक्षित रखें। असंगति छिपाकर फ़ाइनेंस टीम से हर सुबह हाथ से कॉलम का क्रम बदलने को न कहें।

रिहर्सल और रोलबैक की सीमा

कृत्रिम या अनुमत, पहचान हटाए गए उदाहरणों का एक छोटा सेट बनाएँ: सफल पेमेंट, डिक्लाइन, आंशिक रिफ़ंड, होल्ड, देर से आया इवेंट, अनजाना स्टेटस। बाहरी फ़ाइनेंशियल कार्रवाई किए बिना इसे पुराने और नए पार्सर, दोनों से चलाएँ। सिर्फ़ अपलोड की सफलता नहीं, बल्कि अंतिम देनदारियाँ, अमाउंट और एक्सेप्शन की कतार भी मिलाएँ।

अगर पैरलल गणना संभव है, तो नया वर्ज़न पहले ऑब्ज़र्वेशन मोड में नतीजा निकालता है, बिना डेबिट या पेआउट किए। रोलआउट बढ़ाने से पहले दोनों वर्ज़न के बीच का हर अंतर समझाया जाना चाहिए। रुकने की शर्तें तय करें: खोए हुए रिकॉर्ड, ग़लत करेंसी, बिना वजह के अमाउंट या ऑर्डर पूरा करने की अनुमति में बदलाव।

कोड का रोलबैक पहले से बना रिफ़ंड रद्द नहीं करता और डैशबोर्ड की पुरानी सेटिंग अपने-आप वापस नहीं लाता। हर बदलने वाले कंपोनेंट के लिए वापसी का तरीका, उसकी सीमाएँ और पहले से हो चुके ट्रांज़ैक्शन पर की जाने वाली कार्रवाई लिखें। अगर वापसी का रास्ता सपोर्टेड नहीं है, तो योजना में ईमानदारी से आगे बढ़कर सुधार करने का तरीका लिखा होना चाहिए, किसी जादुई बटन का वादा नहीं।

अपडेट को पहले HTTP 200 के बाद नहीं, बल्कि रिपोर्ट और रिकंसिलिएशन समेत पहले पूरे प्रभावित चक्र के बाद बंद करना चाहिए। अंत में टीम के पास बदलाव का एक छोटा पासपोर्ट रहता है: क्या बदला, किन नतीजों की तुलना हुई, रोलआउट बढ़ाने की अनुमति किसने दी और आगे किस पर नज़र रखनी है।