USDC चेकआउट इंटीग्रेशन
चेकआउट पर USDC भुगतान इंटीग्रेट करने की एक व्यावहारिक इंजीनियरिंग गाइड: API पैटर्न, नेटवर्क का चुनाव, वेबहुक आइडेम्पोटेंसी, और प्रोडक्शन में सामने आने वाली विफलताएँ।
संक्षेप में
USDC चेकआउट इंटीग्रेशन एक जाने-पहचाने पैटर्न पर चलता है: अपने सर्वर पर एक पेमेंट इंटेंट बनाएँ (राशि, करेंसी, नेटवर्क की पसंद), अपने एक्वायरर से एक होस्टेड चेकआउट URL या विजेट कॉन्फ़िग पाएँ, खरीदार को उसके वॉलेट में भुगतान करने दें, और पुष्टि वाले वेबहुक को आइडेम्पोटेंट तरीके से संभालें। सबसे ज़्यादा मायने रखने वाले इंजीनियरिंग फ़ैसले हैं: नेटवर्क का चुनाव (एक सेंट से कम शुल्क के लिए Solana या Base को डिफ़ॉल्ट रखें), वेबहुक आइडेम्पोटेंसी (ऑर्डर ID + tx हैश का उपयोग करें), रिफ़ंड फ़्लो (चेकआउट पर वॉलेट पता लें, रिफ़ंड API दें), और वॉलेट-साइनिंग चरण के लिए सहज UX (मोबाइल वॉलेट में डीप-लिंक करें, डेस्कटॉप के लिए QR पर फ़ॉलबैक करें)। सही ढंग से किया जाए तो USDC चेकआउट शुरू से अंत तक 30 सेकंड से कम में पूरा होता है और एक्वायरर के अनुसार मर्चेंट को 0.3%–1% की लागत आती है।
मानक API ढाँचा
USDC एक्वायरिंग API मोटे तौर पर उसी पेमेंट-इंटेंट पैटर्न पर चलते हैं जिसे Stripe ने लोकप्रिय बनाया। न्यूनतम ढाँचा:
सर्वर पेमेंट इंटेंट बनाता है
POST /v1/payments, जिसकी बॉडी मेंamount,currency(फ़िएट में क्वोट करने पर USD; स्टेबलकॉइन में क्वोट करने पर USDC),settlement_preference(USDC बनाम फ़िएट),networks(अनुमत सूची),order_id(आपकी आइडेम्पोटेंसी की),success_url,cancel_url, और आपके अपने मिलान (reconciliation) के लिए एकmetadataब्लॉब हो।एक्वायरर चेकआउट URL या विजेट कॉन्फ़िग लौटाता है
होस्टेड चेकआउट के लिए: एक URL जिस पर खरीदार को रीडायरेक्ट किया जाता है। एम्बेडेड विजेट के लिए: एक क्लाइंट-साइड कॉन्फ़िग (publishable key, इंटेंट ID) जिसे विजेट लोड करता है। दोनों फ़्लो वॉलेट की पहचान, नेटवर्क का चुनाव और क्वोट दिखाना संभालते हैं।
खरीदार वॉलेट में साइन करता है, ऑन-चेन ट्रांसफ़र ब्रॉडकास्ट होता है
मोबाइल: MetaMask, Phantom, Trust आदि में डीप-लिंक। डेस्कटॉप: WalletConnect QR या ब्राउज़र-एक्सटेंशन पॉपअप। खरीदार राशि की समीक्षा करता है और साइन करता है।
एक्वायरर कन्फ़र्मेशन का इंतज़ार करता है, वेबहुक भेजता है
POST your_webhook_url, जिसके पेलोड मेंevent_type: “payment.succeeded”,order_id,amount,tx_hash,network, और एक सिग्नेचर हो जिसे आप एक्वायरर के webhook secret से सत्यापित करते हैं।सर्वर आइडेम्पोटेंट तरीके से ऑर्डर को paid मार्क करता है
वेबहुक सिग्नेचर सत्यापित करें, अपने DB में
(order_id, tx_hash)देखें, अगर पहले से मार्क नहीं है तो paid मार्क करें, फ़ुलफ़िलमेंट शुरू करें।
नेटवर्क का चुनाव
कौन-से नेटवर्क स्वीकार करने हैं, यह चुनाव UX और लागत के बीच का संतुलन है:
- Solana: एक सेंट से कम नेटवर्क शुल्क, एक सेकंड से कम में पुष्टि। छोटे AOV के लिए सबसे अच्छा डिफ़ॉल्ट।
- Base: कुछ सेंट नेटवर्क शुल्क, कुछ सेकंड में पुष्टि। मज़बूत वॉलेट सपोर्ट; क्रिप्टो-नेटिव ऑडियंस के लिए अच्छा डिफ़ॉल्ट।
- Polygon, Arbitrum: शुल्क और गति Base जैसी। जोड़ना ठीक है, लेकिन बिल्कुल ज़रूरी नहीं।
- Ethereum mainnet: gas के अनुसार $1–$8+ नेटवर्क शुल्क। छोटे ऑर्डर पर खरीदारों के लिए तकलीफ़देह। ऊँचे AOV (>$500) के लिए या फ़ॉलबैक के रूप में स्वीकार करें।
- Tron: अगर आप एशिया/अफ़्रीका के USDT फ़्लो को लक्ष्य बना रहे हैं, तो USDC के साथ USDT-TRON को सपोर्ट करने पर विचार करना उचित है।
वेबहुक आइडेम्पोटेंसी
वेबहुक दोबारा भेजे जाते हैं (रीट्राई)। आपका हैंडलर आइडेम्पोटेंट होना चाहिए। मानक पैटर्न:
- अपने एक्वायरर के secret के साथ HMAC-SHA256 का उपयोग करके वेबहुक सिग्नेचर सत्यापित करें।
- पेलोड से
(order_id, tx_hash)निकालें। - अपनी
processed_paymentsटेबल में वह जोड़ी देखें। - अगर मिल जाए: कुछ और किए बिना 200 OK लौटाएँ।
- अगर न मिले: पंक्ति इन्सर्ट करें (जोड़ी पर UNIQUE constraint के साथ), फिर अपनी मुख्य ऑर्डर टेबल में ऑर्डर को paid मार्क करें, फिर फ़ुलफ़िलमेंट शुरू करें।
- चरण 5 को एक ही DB ट्रांज़ैक्शन में रखें, ताकि बीच में क्रैश होने पर दोहरा फ़ुलफ़िलमेंट न हो।
ज़्यादातर एक्वायरिंग वेबहुक में एक डिलीवरी ID होती है, डीबगिंग के लिए उसे लॉग करें, लेकिन आइडेम्पोटेंसी की के रूप में उस पर निर्भर न रहें। नेटवर्क कन्फ़र्मेशन और एक्वायरर के रीट्राई से ऐसे डुप्लिकेट payment.succeeded इवेंट बन सकते हैं जिनकी डिलीवरी ID अलग हो लेकिन tx_hash एक ही हो; आपका डीडुप्लिकेशन ऑन-चेन पहचान पर होना चाहिए, डिलीवरी पर नहीं।
रिफ़ंड फ़्लो
दो पैटर्न सबसे ज़्यादा चलते हैं:
- भेजने वाले को रिफ़ंड: एक्वायरर USDC उसी पते पर वापस भेजता है जिससे खरीदार ने मूल भुगतान किया था। सबसे साफ़ UX; यह इसलिए काम करता है क्योंकि ऑन-चेन भुगतान रिकॉर्ड में स्रोत पता मौजूद होता है।
- तय किए गए पते पर रिफ़ंड: खरीदार रिफ़ंड का गंतव्य बताता है (अगर उसने किसी एक्सचेंज या हॉट वॉलेट से भुगतान किया हो, तो यह स्रोत से अलग हो सकता है)। ज़्यादातर एक्वायरर इसे
destination_addressके साथPOST /v1/refundsके ज़रिए सपोर्ट करते हैं।
रिफ़ंड वाले हिस्से पर नेटवर्क शुल्क मर्चेंट चुकाता है। पूरे और आंशिक, दोनों तरह के रिफ़ंड सपोर्ट होते हैं। रिफ़ंड में भी ऑन-चेन पुष्टि का उतना ही समय लगता है जितना मूल भुगतान में।
प्रोडक्शन में विफलता के तरीके
- खरीदार साइन करने के बाद छोड़ देता है। ऑन-चेन ट्रांसफ़र ब्रॉडकास्ट हो जाता है, लेकिन वेबहुक आने से पहले खरीदार टैब बंद कर देता है। एक्वायरर फिर भी ऑन-चेन मॉनिटरिंग के ज़रिए भुगतान पहचानता और पुष्ट करता है; आपका फ़ुलफ़िलमेंट वेबहुक से चलता है, रीडायरेक्ट से नहीं।
- खरीदार गलत राशि भेजता है। ज़्यादातर एक्वायरर ऑन-चेन पहचान के समय मेल न खाने वाली राशि को अस्वीकार कर देते हैं। कुछ अनुमानित मिलान (एक तय सहनसीमा के भीतर) की अनुमति देते हैं और अंतर को वेबहुक में दिखाते हैं।
- खरीदार गलत नेटवर्क पर भुगतान करता है। अगर वह Ethereum पर साइन करता है लेकिन आप केवल Solana स्वीकार करते हैं, तो भुगतान आपके एक्वायरर की मॉनिटरिंग से पूरी तरह छूट जाता है। ज़्यादातर प्रदाता रिकवरी फ़्लो के ज़रिए फ़ंड लौटा देते हैं; कुछ के यहाँ फ़ंड खो जाते हैं। चेकआउट पर नेटवर्क का चुनाव स्पष्ट रखें।
- खरीदार किसी एक्सचेंज पते से भुगतान करता है। स्रोत पर रिफ़ंड लौट सकता है या गलत खाते में पहुँच सकता है। जिस भी प्रोडक्ट में रिफ़ंड की संभावना हो, उसके लिए चेकआउट पर ही रिफ़ंड गंतव्य पता स्पष्ट रूप से लें।
- स्टेबलकॉइन डीपेग। दुर्लभ, लेकिन वास्तविक। अगर क्वोट और ऑन-चेन सेटलमेंट के बीच की छोटी-सी अवधि में USDC काफ़ी हद तक डीपेग हो जाए, तो समझौते के अनुसार अंतर मर्चेंट या एक्वायरर वहन करता है।
DPT Acquiring के साथ USDC चेकआउट जोड़ें
प्रति लेन-देन 0.3% से। USDC या फ़िएट में उसी दिन सेटलमेंट। होस्टेड चेकआउट URL या एम्बेड करने योग्य विजेट। SDK और वेबहुक डॉक्यूमेंटेशन merchant.dpt.xyz पर।