पुनः प्रयास और डुप्लिकेट से सुरक्षा वाला सर्वर-साइड भुगतान प्रवाह।
1. ID और ऐक्सेस तैयार करें
चालू स्टोर और जाँची गई भुगतान विधियों से शुरू करें। यहाँ सेटिंग → API पहुँचमें केवल ज़रूरी प्रोजेक्ट तक सीमित पढ़ने/लिखने का क्रेडेंशियल बनाएँ। टोकन अपने बैकएंड पर रखें, ब्राउज़र कोड या सार्वजनिक रिपॉज़िटरी में कभी नहीं।
कॉपी करें प्रोजेक्ट API ID और स्टोर API ID स्टोर के बुनियादी → API ID बॉक्स से। ये UUID हैं, पढ़ने योग्य प्रोजेक्ट पहचानकर्ता या आपका ऑर्डर नंबर नहीं। अपना API होस्टनेम इस्तेमाल करें।
यहाँ: स्टोर → IPNमें साइनिंग सीक्रेट बनाएँ, इससे पहले कि आप दें: ipn_url। आपका HTTPS रिसीवर मर्चेंट VPS से पहुँचा जा सकना चाहिए।
2. इनवॉइस बनाएँ
प्लेसहोल्डर बदलें और यह अनुरोध अपने बैकएंड से भेजें। राशि दशमलव स्ट्रिंग होती है, फ़्लोटिंग-पॉइंट गणना नहीं।
curl --fail-with-body --request POST \
'https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices' \
--header 'Authorization: Bearer YOUR_MERCHANT_API_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-1042-attempt-1' \
--data '{
"amount": "10.00",
"currency": "EUR",
"order_id": "order-1042",
"description": "Example order",
"ipn_url": "https://shop.example.com/payments/wholly-ipn",
"metadata": {
"cart_id": "cart-1042"
}
}'सहेजें data.invoice_id अपने ऑर्डर के साथ, फिर ग्राहक को यहाँ रीडायरेक्ट करें: links.checkout। नए भुगतान प्रयास के लिए अनोखी idempotency कुंजी इस्तेमाल करें। टाइमआउट पर फिर कोशिश करते समय रखें: वही क्रेडेंशियल, कुंजी और बॉडी के ठीक वही बाइट्स.
छोड़ने पर payment_methods स्टोर की स्वीकार की गई विधियाँ इस्तेमाल होती हैं। चेन स्लग और टिकर से हर इनवॉइस पर इन्हें सीमित कर सकते हैं; इससे अस्वीकार किया गया एसेट कभी चालू नहीं होता। सभी अनुरोध फ़ील्ड और रिस्पॉन्स उदाहरण →
3. IPN, webhook या दोनों चुनें
IPN इनवॉइस के जीवनचक्र का अनुसरण करता है। स्टोर का डिफ़ॉल्ट IPN URL सेट करें या इसे बदलें: ipn_url किसी इनवॉइस के लिए। वेबहुक किसी एंडपॉइंट को चुने इवेंट की सदस्यता देते हैं, जैसे invoice.settled.
वे एक ही हस्ताक्षर फ़ॉर्मैट इस्तेमाल करते हैं, लेकिन अलग सीक्रेट: IPN स्टोर का IPN सीक्रेट इस्तेमाल करता है; हर webhook एंडपॉइंट का अपना सीक्रेट है। कोई भी हस्ताक्षर के लिए API bearer टोकन इस्तेमाल नहीं करता।
दोनों आपके ऐप को भेजें तो एक ही घटना की कई सूचनाएँ आ सकती हैं। ऑर्डर को दो बार क्रेडिट न दें।
4. सूचना सत्यापित करें और सहेजें
- JSON पार्स करने से पहले अनुरोध की ठीक वही रॉ बॉडी पढ़ें। सत्यापित करें
Wholly-Signatureसंबंधित सीक्रेट और टाइमस्टैम्प/रीप्ले जाँच के साथ। आधिकारिक SDK सत्यापन फ़ंक्शन देते हैं। - हस्ताक्षरित बॉडी के प्रोजेक्ट, स्टोर, इनवॉइस और इवेंट की पहचान जाँचें। बिना हस्ताक्षर वाले डिलीवरी हेडर प्रमाणीकरण का स्रोत नहीं हैं।
- इवेंट को टिकाऊ स्टोरेज में अनोखे
event_idके साथ सहेजें, फिर तुरंत HTTP 2xx लौटाएँ। ऑर्डर बैकग्राउंड वर्कर में प्रोसेस करें। - अपने कॉन्फ़िगर किए API होस्ट से मौजूदा इनवॉइस लें, अनुरोध में दिए किसी मनमाने होस्ट से नहीं। अपने सहेजे प्रोजेक्ट, स्टोर, राशि, मुद्रा और ऑर्डर संदर्भ से तुलना करें।
PHP · Python · JavaScript / TypeScript · हस्ताक्षर विनिर्देश और रिसीवर उदाहरण
5. निपटान होने पर केवल एक बार ऑर्डर पूरा करें
किसी इवेंट-आधारित रिसीवर में सँभालें event_type = invoice.settledफिर मौजूदा स्थिति सत्यापित करें: status = settled और अपनी अपवाद नीति जाँचें। डेटाबेस ट्रांज़ैक्शन/अनोखे ऑर्डर प्रतिबंध के तहत केवल एक बार ऑर्डर पूरा करें।
जल्दी अंतिम पुष्टि वाली चेन दोनों भेज सकती है: payment.received और invoice.settled इसके साथ: status = settled। दूसरी चेन पर payment.received में अभी भी processing हो सकता है। दोनों में कोई त्रुटि नहीं है।
इवेंट के डुप्लिकेट हटाने के लिए इस्तेमाल करें event_idकेवल sequence नहीं: अलग इवेंट प्रकार एक sequence साझा कर सकते हैं। इसके बजाय स्थिति-आधारित SDK हैंडलर इनवॉइस संशोधन को एकीकृत करते हैं और इवेंट प्रकार की परवाह किए बिना स्थिति जाँचते हैं। उस एकीकरण को इवेंट-प्रकार फ़िल्टर के साथ न मिलाएँ। दोनों तरीकों में फिर भी ऑर्डर-स्तरीय डुप्लिकेट सुरक्षा चाहिए।
जाँचें requires_review और ऑर्डर पूरा करने से पहले मैन्युअल समाधान देखें। amount_status = paid अकेले पुष्टि का प्रमाण नहीं है। शीर्ष-स्तर के भुगतान किए एसेट फ़ील्ड निपटान का सार देते हैं; payment_info में विस्तृत प्राप्तियाँ और कोट डेटा रहता है। सभी स्थितियाँ, इवेंट और अपवाद नियम →
6. पुनः प्रयास और रिकवरी जाँचें
छोटा भुगतान, डुप्लिकेट डिलीवरी, समाप्त इनवॉइस और अस्थायी रूप से अनुपलब्ध रिसीवर जाँचें। इवेंट दोबारा चलाने से ऑर्डर को दूसरी बार क्रेडिट नहीं मिलना चाहिए। क्रम से बाहर आने वाले इवेंट सँभालें, बिना नई स्थिति के ऊपर पुरानी लिखे।
जाँचें स्टोर → IPN / वेबहुक → इतिहास → विवरणया इनवॉइस विवरण के डिलीवरी भाग देखें। दोबारा भेजना रिकॉर्ड किए इवेंट को फिर इस्तेमाल करता है, नया निपटान नहीं बनाता।
कम प्रोसेसिंग क्रेडिट IPN/webhook रोक देता है जबकि भुगतान जारी रहते हैं। API से लंबित ऑर्डर का मिलान करें और रिकवरी के बाद बची डिलीवरी सँभालें। ब्राउज़र रीडायरेक्ट या ग्राहक के स्क्रीनशॉट से ऑर्डर कभी पूरा न करें।