प्रोटोकॉल के स्टैंडर्ड

एपीआई, एचटीटीपी एपीआई के मानकों का पालन करता है. साथ ही, बेहतर इंटिग्रेशन के लिए, idempoency पर काम करता है.

Google की मदद से होस्ट किए गए यूआरएल

Google के होस्ट किए गए हर तरीके के लिए दस्तावेज़ में एक बेस यूआरएल दिया जाता है. इसमें तरीके का नाम और मेजर वर्शन नंबर शामिल होता है. पूरा यूआरएल, कॉल करने वाले के पेमेंट इंटीग्रेटर खाता आईडी को आखिर में जोड़कर बनाया जाता है. उदाहरण के लिए, Google के होस्ट किए गए इको के तरीके वाले दस्तावेज़ में, यूआरएल के बारे में बताया जाता है:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

अगर कॉल करने वाले का पेमेंट इंटीग्रेटर खाता आईडी INTEGRATOR_1 है, तो वह इसे फ़ॉर्म के यूआरएल के आखिर में जोड़ देगा:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

ध्यान दें: आपने जिस तरीके का इस्तेमाल किया है उसके एंडपॉइंट दस्तावेज़ पेज पर, आपके मामले के लिए सबसे सटीक यूआरएल होगा.

पार्टनर के होस्ट किए गए यूआरएल

पार्टनर के होस्ट किए गए हर एपीआई तरीके के दस्तावेज़ में एक बेस यूआरएल होता है. इसमें तरीके का नाम और मेजर वर्शन नंबर शामिल होता है. आपको अपने होस्ट किए गए यूआरएल में, पेमेंट इंटीग्रेटर खाता आईडी (PIAID) शामिल नहीं करना चाहिए.

सैंडबॉक्स और प्रोडक्शन एनवायरमेंट

Google, सैंडबॉक्स (डेवलपमेंट और टेस्टिंग के लिए) और प्रोडक्शन, दोनों में स्टैंडर्ड पेमेंट एपीआई को होस्ट करता है. Google सैंडबॉक्स एनवायरमेंट में किए गए अनुरोधों की वजह से, असल में वित्तीय जवाबदेही नहीं होती. सैंडबॉक्स और प्रोडक्शन एनवायरमेंट एक-दूसरे से बिलकुल अलग होते हैं और इनमें कुंजियों या लेन-देन की जानकारी शेयर नहीं की जाती है.

Google को उम्मीद है कि आपका सैंडबॉक्स लगातार उपलब्ध रहेगा, क्योंकि हम सैंडबॉक्स का इस्तेमाल पहले टेस्ट बदलावों और नई सुविधाओं को करने के लिए करेंगे.

Google का सैंडबॉक्स बेस पाथ

https://vgw.sandbox.google.com/secure-serving/gsp/

ध्यान दें: अगर आपका इंटिग्रेशन पहले ही लॉन्च हो चुका है और https://billpaynotification.sandbox.googleapis.com होस्ट को कॉल करता है, तो आगे भी ऐसा किया जा सकता है. नए इंटिग्रेशन को 'vgw.sandbox.google.com' होस्ट को कॉल करना चाहिए.

Google का प्रोडक्शन बेस पाथ

https://vgw.googleapis.com/secure-serving/gsp/

ध्यान दें: अगर आपका इंटिग्रेशन पहले ही लॉन्च हो चुका है और https://billpaynotification.googleapis.com होस्ट को कॉल करता है, तो ऐसा करना जारी रखें. नए इंटिग्रेशन को 'vgw.googleapis.com' होस्ट को कॉल करना चाहिए.

इस गाइड में, प्रोडक्शन एंडपॉइंट का इस्तेमाल किया जाएगा.

कॉन्टेंट का टाइप और एन्कोडिंग

PGP एन्क्रिप्शन का इस्तेमाल करने वाले मैसेज पेलोड को कॉन्टेंट टाइप application/octet-stream; charset=utf-8 का इस्तेमाल करना होगा. PGP के अनुरोध के मुख्य हिस्से, base64url एन्कोडिंग का इस्तेमाल करके भेजे जाने चाहिए, जैसा कि rfc4648 §5 में बताया गया है. मैसेज पेलोड जो JWE एन्क्रिप्शन का इस्तेमाल करते हैं उन्हें कॉन्टेंट टाइप application/jose; charset=utf-8 का इस्तेमाल करना होगा. JWE/JWS के साथ काम करने वाला कॉम्पैक्ट सीरियलाइज़ेशन विकल्प, अनुरोध के मुख्य हिस्से के लिए एन्कोडिंग को हैंडल करता है.

एचटीटीपी स्टेटस कोड

स्टैंडर्ड पेमेंट एपीआई को इस तरह से डिज़ाइन किया गया है कि यह ऐसे सभी अनुरोधों के लिए एक एचटीटीपी 200 स्टेटस कोड दिखाता है जिन्हें सर्वर प्रोसेस किया जा सकता है. इसमें कारोबार या ऐप्लिकेशन लॉजिक के हिसाब से, पूरे हो चुके और अस्वीकार किए गए, दोनों तरह के अनुरोध शामिल होते हैं. जिन अनुरोधों को प्रोसेस नहीं किया जा सकता उनकी वजह से एचटीटीपी 200 स्टेटस कोड नहीं मिलना चाहिए, क्योंकि इनसे Google और पार्टनर के बीच कोई गड़बड़ी दिखती है. इसके बजाय, एपीआई रिस्पॉन्स को वैकल्पिक ErrorResponse ऑब्जेक्ट के साथ, नीचे दिए गए सही एचटीटीपी स्टेटस कोड का इस्तेमाल करना चाहिए.

एचटीटीपी गड़बड़ियां और वजहें
400	BAD REQUEST क्लाइंट ने एक अमान्य तर्क बताया. अगर कार्रवाई को पूरा नहीं किया गया है, तो भी इसे वापस किया जा सकता है, क्योंकि सिस्टम, कार्रवाई पूरी करने के लिए ज़रूरी स्थिति में नहीं है. अगर सिस्टम की स्थिति को साफ़ तौर पर ठीक किए बिना, बार-बार अनुरोध किया जा सकता है, तो इसका इस्तेमाल करें. उदाहरण के लिए, अगर रिफ़ंड का अनुरोध इसलिए पूरा नहीं हो पाता, क्योंकि उसमें ऐसे कैप्चर का रेफ़रंस दिया गया है जो मौजूद नहीं है, तो फिर से कोशिश करने से तब तक काम नहीं होगा, जब तक कैप्चर किया गया डेटा, इंटिग्रेटर सिस्टम में मौजूद नहीं होता. ध्यान दें: BAD_REQUEST (400) का इस्तेमाल उन स्थितियों में नहीं किया जाना चाहिए जहां ऐप्लिकेशन की सही गड़बड़ी मौजूद हो. उदाहरण के लिए, अगर स्टैंडर्ड रिस्पॉन्स में वह फ़ील्ड या Enum है, तो गलत मुद्राओं में कोड 200 के साथ ACCOUNT_DOES_NOT_SUPPORT_CURRENCY दिखना चाहिए.
401	UNAUTHORIZED अनुरोध में कार्रवाई के लिए, पुष्टि करने के मान्य क्रेडेंशियल नहीं हैं. उदाहरण के लिए, अमान्य हस्ताक्षर या अनजान हस्ताक्षरों पर 401 कोड वाली गड़बड़ी दिखनी चाहिए.
403	FORBIDDEN / PERMISSION DENIED कॉल करने वाले के पास यह कार्रवाई करने की अनुमति नहीं है.
404	NOT FOUND अनुरोध की गई कोई इकाई नहीं मिली, जैसे कि पेमेंट या उपयोगकर्ता.
409	CONFLICT / ABORTED आम तौर पर, सीक्वेंसर की जांच न कर पाने, लेन-देन रद्द होने जैसी कई समस्याओं की वजह से, कार्रवाई को रद्द किया गया.
412	PRECONDITION FAILED इस कोड का इस्तेमाल ऐसे मामलों में किया जाना चाहिए जहां अलग-अलग पैरामीटर के साथ आईडी एम्पॉटेंसी कुंजी का फिर से इस्तेमाल किया जा रहा हो.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS कुछ सिस्टम संसाधन खत्म हो गए हैं.
499	CANCELLED कार्रवाई रद्द कर दी गई थी (आम तौर पर कॉलर के ज़रिए).
500	INTERNAL ERROR अंदरूनी गड़बड़ियां. इसका मतलब है कि सिस्टम के कुछ ऐसे वैरिएंट काम नहीं कर रहे हैं जिनकी उम्मीद की जा सकती है.
501	UNIMPLEMENTED इस सेवा में ऑपरेशन लागू, समर्थित या सक्षम नहीं किया गया है.
503	UNAVAILABLE फ़िलहाल, सेवा उपलब्ध नहीं है. यह समस्या कुछ समय के लिए होती है और फिर से कोशिश करके इसे ठीक किया जा सकता है.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED कार्रवाई पूरी होने से पहले, समयसीमा खत्म हो गई. सिस्टम की स्थिति बदलने वाली कार्रवाइयों के लिए, यह गड़बड़ी तब भी दिख सकती है, जब कार्रवाई पूरी हो गई हो. उदाहरण के लिए, हो सकता है कि किसी सर्वर से रिस्पॉन्स मिलने में, तय की गई समयसीमा खत्म होने में काफ़ी देरी हो.

पहचान बताने के लिए अनुरोध करें

अनुरोध का पता लगाने की सुविधा, स्टैंडर्ड पेमेंट एपीआई में इस्तेमाल की जाने वाली एक मुख्य रणनीति है. इसका इस्तेमाल यह पक्का करने के लिए किया जाता है कि Google और पार्टनर के बीच सिस्टम से होने वाली बातचीत अच्छी तरह से और गड़बड़ियों को भी झेल सके. ग़ैर-ज़रूरी अनुरोध ऐसे अनुरोध होते हैं जो कई बार भेजे जा सकते हैं. हालांकि, उनका असर एक ही अनुरोध की तरह ही होता है. यह रणनीति, प्रोसेस को सुरक्षित बनाकर सिस्टम के बीच एक जैसा व्यवहार बनाए रखने में मदद करती है. इससे हमारे सिस्टम, संसाधन की स्थिति के हिसाब से समझौता कर पाते हैं.

हमारा एपीआई इन कामों के लिए पहचान बताता है:

• सभी कार्रवाइयों को आसानी से ट्रेस करने और सुनने लायक बनाकर, मिलान वाली समस्याओं को कम करना चाहिए.
• यह पक्का करके नस्ल की स्थितियों को रोकता है कि एक ही क्लाइंट से एक जैसे कई अनुरोधों की वजह से एक अलग आखिरी स्थिति न बने.
• अनुरोधों को एक-दूसरे से अलग रखकर समझने की अनुमति देकर, स्थिति को कम करने के लिए किया जा सकता है. इससे, डेटा को सेव रखने की वजह से होने वाले सर्वर लोड को हटाकर, परफ़ॉर्मेंस और डेटा की क्षमता को बेहतर बनाया जा सकता है.
• दोबारा कोशिश करने का अनुरोध है या नहीं, यह बताने के लिए अतिरिक्त फ़ील्ड की ज़रूरत से बचें

ध्यान दें: गड़बड़ी के नतीजों को कभी भी कैश मेमोरी में सेव नहीं किया जाना चाहिए या बिना किसी पहचान के उन्हें दिखाया जाना चाहिए. साथ ही, गड़बड़ियों के लिए अपने-आप होने वाली कोशिशों में, एक्स्पोनेंशियल बैकऑफ़ रणनीति का इस्तेमाल करना ज़रूरी है.

उदाहरण

पहला उदाहरण: जवाब मिलने से पहले ही कनेक्टिविटी टूटना

स्थिति:

1. Google, इंटिग्रेटर को एक अनुरोध भेजता है.
2. इंटिग्रेटर सर्वर को यह अनुरोध मिलता है और वह इसे प्रोसेस कर देता है.
3. चरण #2 में जवाब पाने से पहले ही, Google के सर्वर में पावर सप्लाई बंद हो गई है.
4. Google का सर्वर फिर से चालू किया जाता है. साथ ही, इंटिग्रेटर के सर्वर को एक ही अनुरोध को सभी समान पैरामीटर (अनुरोध आईडी और अनुरोध की जानकारी, लेकिन requestTimestamp अपडेट किया गया) के साथ भेजा जाता है.

नतीजा:

इस मामले में, इंटिग्रेटर सर्वर को दूसरे चरण में दिए गए जवाब के साथ ही जवाब देना होगा, क्योंकि responseTimestamp को छोड़कर सभी पैरामीटर एक जैसे होते हैं. खराब असर सिर्फ़ एक बार, दूसरे चरण में होता है. चौथे चरण का कोई खराब असर नहीं पड़ता.

दूसरा उदाहरण: ऐसे सर्वर को भेजा गया अनुरोध जो रखरखाव में है

स्थिति:

1. इंटिग्रेटर सर्वर का डेटाबेस, रखरखाव के लिए काम नहीं कर रहा है.
2. Google, इंटिग्रेटर को एक अनुरोध भेजता है.
3. इंटिग्रेटर सही तरीके से UNAVAILABLE स्टेटस कोड दिखाता है.
4. Google के सर्वर को जवाब मिलता है और वह फिर से कोशिश करने के लिए शेड्यूल करता है.
5. इंटिग्रेटर सर्वर का डेटाबेस फिर से ऑनलाइन हो जाता है.
6. Google दूसरे चरण से अनुरोध को फिर से भेजता है (अनुरोध का एक ही आईडी और जानकारी अपडेट की गई है, लेकिन requestTimestamp अपडेट की गई है). ध्यान दें कि दोनों अनुरोधों के लिए एक ही अनुरोध आईडी होना चाहिए.
7. इंटिग्रेटर सर्वर को अनुरोध मिलता है और वह पूरे रिस्पॉन्स के साथ OK स्टेटस कोड दिखाता है.

नतीजा:

इस स्थिति में, इंटिग्रेटर सर्वर को चरण #7 में अनुरोध को प्रोसेस करना होगा और एचटीटीपी 503 (UNAVAILABLE) नहीं दिखाना चाहिए. इसके बजाय, इंटिग्रेटर सर्वर को अनुरोध को पूरी तरह से प्रोसेस करना चाहिए और सही मैसेज के साथ 'ठीक है' के तौर पर मिलना चाहिए. ध्यान दें कि सिस्टम UNAVAILABLE है. इसके बावजूद, Google दूसरे चरण से मिलते-जुलते अनुरोध बार-बार कर सकता है. हर अनुरोध के लिए, तीसरे चरण से मिलता-जुलता मैसेज मिलना चाहिए. आखिर में, चरण #6 और चरण #7 होंगे.

उदाहरण 3: रिकवरी की गड़बड़ी की वजह से, फिर से कोशिश किया गया मैसेज, शुरुआती मैसेज से मेल नहीं खाता

स्थिति:

1. Google, इंटिग्रेटर को एक अनुरोध भेजता है.
2. इंटिग्रेटर सर्वर को यह अनुरोध मिलता है और वह इसे प्रोसेस कर देता है.
3. चरण #2 में जवाब पाने से पहले ही, Google के सर्वर में पावर सप्लाई बंद हो गई है.
4. Google का सर्वर फिर से चालू हो जाता है और वह वही अनुरोध भेजने की कोशिश करता है लेकिन कुछ पैरामीटर अलग होते हैं.

नतीजा:

ऐसे में, इंटिग्रेटर सर्वर को एक एचटीटीपी 412 (PRECONDITION FAILED) गड़बड़ी कोड के साथ जवाब देना चाहिए, जो Google को बताता है कि इस सिस्टम में कोई गड़बड़ी है.