VibeFox Braintree for PrestaShop — सहायता

आवश्यकताएँ

PrestaShop: 8.0 से 9.x।

PHP: 8.0 या उसके बाद का संस्करण। पुराने PHP संस्करणों पर मॉड्यूल इंस्टॉल नहीं होगा।

Braintree खाता: आपको अपने Braintree खाते का Merchant ID, Public Key और Private Key चाहिए। ये Braintree Control Panel में (sandbox: sandbox.braintreegateway.com, live: www.braintreegateway.com) गियर आइकन के नीचे, API, API Keys पर मिलते हैं। सैंडबॉक्स और लाइव खातों की कुंजियाँ अलग होती हैं। जब तक आप 3-D Secure को Disabled पर सेट न करें, आपके Braintree मर्चेंट खाते के लिए 3-D Secure सक्षम होना चाहिए। वेबहुक की ज़रूरत नहीं है: कार्ड भुगतान तुरंत पुष्ट हो जाते हैं।

VibeFox लाइसेंस कुंजी: vibefox.net पर खरीदी जाती है। एक कुंजी एक ही डोमेन पर काम करती है।

इंस्टॉलेशन

1. बैक ऑफ़िस में Modules > Module Manager पर जाएँ और Upload a module पर क्लिक करें। मॉड्यूल की ZIP फ़ाइल चुनें।

2. अपलोड पूरा होने पर Configure पर क्लिक करें, या बाद में मॉड्यूल सूची में VibeFox Braintree Gateway खोजकर Configure पर क्लिक करें।

3. Configure पेज के ऊपर वाले लाइसेंस ब्लॉक में License key में अपनी VibeFox लाइसेंस कुंजी दर्ज करें और Activate पर क्लिक करें (देखें लाइसेंस कुंजी)।

4. Braintree Control Panel से Merchant ID, Public Key और Private Key कॉपी करके सैंडबॉक्स या लाइव फ़ील्ड में डालें।

5. Enable/Disable चालू करें और Save पर क्लिक करें। Sandbox mode चालू रखें और Braintree सैंडबॉक्स टेस्ट कार्ड से एक टेस्ट ऑर्डर दें। फिर वास्तविक भुगतान लेने के लिए लाइव क्रेडेंशियल के साथ Sandbox mode बंद करें।

इंस्टॉल होने पर मॉड्यूल दो ऑर्डर स्थितियाँ बनाता है: Braintree payment authorized और Braintree payment on hold। PrestaShop सभी मुद्राओं, देशों और ग्राहक समूहों के लिए एक नया भुगतान मॉड्यूल देता है। आप इन्हें Payment > Preferences में सीमित कर सकते हैं।

कॉन्फ़िगरेशन

सभी सेटिंग्स मॉड्यूल पेज पर हैं: Modules > Module Manager > VibeFox Braintree Gateway > Configure। हर सेक्शन का अपना Save बटन है, जो पूरा पेज सेव करता है। जब भुगतान विधि सक्षम हो, पर चुने गए वातावरण का Merchant ID, Public Key या Private Key खाली हो, तो पेज चेतावनी देता है कि उनके भरे जाने तक चेकआउट पर भुगतान विधि छिपी रहेगी। जब सैंडबॉक्स मोड चालू हो, तब पेज पर Sandbox mode is on: test payments, no real money. दिखता है।

Braintree

Enable/Disable: Enable Braintree card payments भुगतान विधि को चालू या बंद करता है। डिफ़ॉल्ट: off।

Title: वह भुगतान विधि का नाम जो ग्राहक चेकआउट पर देखते हैं। ऑर्डर में भी यही भुगतान विधि का नाम सेव होता है। डिफ़ॉल्ट: Credit / debit card। अनिवार्य।

Description: चेकआउट पर भुगतान विधि के नीचे दिखाया जाने वाला पाठ। डिफ़ॉल्ट: Pay securely with your credit or debit card via Braintree.

API क्रेडेंशियल

Braintree Control Panel (सैंडबॉक्स या लाइव) में लॉग इन करें, गियर आइकन पर क्लिक करें, फिर API और API Keys पर क्लिक करें। वहाँ Public Key और Private Key सूचीबद्ध हैं, और Merchant ID उसी पेज पर दिखता है। यह पेज केवल चुने गए वातावरण के क्रेडेंशियल फ़ील्ड दिखाता है; दोनों सेट सेव रहते हैं।

Sandbox mode: Braintree सैंडबॉक्स का उपयोग करता है (टेस्ट भुगतान, कोई वास्तविक पैसा नहीं)। डिफ़ॉल्ट: on। लाइव क्रेडेंशियल से वास्तविक भुगतान लेने के लिए इसे बंद करें। रिफ़ंड, कैप्चर और void हमेशा उसी वातावरण में होते हैं जिसमें ऑर्डर का भुगतान हुआ था। चालू रहने पर ग्राहकों को भुगतान विधि के नीचे SANDBOX / TEST MODE — no real money is charged. दिखता है।

Sandbox Merchant ID और Live Merchant ID: सैंडबॉक्स या लाइव खाते का Merchant ID।

Sandbox Public Key और Live Public Key: उस खाते की Public Key।

Sandbox Private Key और Live Private Key: उस खाते की Private Key। सेव की गई Private Keys दोबारा कभी नहीं दिखाई जातीं। फ़ील्ड खाली रहता है और Saved — leave empty to keep it. दिखाता है। केवल बदलने के लिए नया मान दर्ज करें।

Sandbox merchant account ID(s) और Live merchant account ID(s): वैकल्पिक। Braintree मर्चेंट खाते की मुद्रा में चार्ज करता है। अपना डिफ़ॉल्ट मर्चेंट खाता उपयोग करने के लिए खाली छोड़ें, या एक ID (उदाहरण के लिए mystore_EUR) या हर मुद्रा के लिए एक ID दर्ज करें: EUR=mystore_EUR, USD=mystore_USD। यदि चार्ज की गई मुद्रा ऑर्डर की मुद्रा से मेल नहीं खाती, तो लेन-देन अपने-आप void हो जाता है और ग्राहक से शुल्क नहीं लिया जाता।

Clear saved private keys: Sandbox Private Key या Live Private Key पर टिक करें और उसे हटाने के लिए Save पर क्लिक करें। खाली फ़ील्ड सेव किया हुआ मान बनाए रखता है।

भुगतान

Transaction type: कार्ड से शुल्क कैसे लिया जाए।

3-D Secure: EEA और UK में अधिकांश कार्ड भुगतानों के लिए 3-D Secure 2 (Strong Customer Authentication) अनिवार्य है। यह आपके Braintree खाते के लिए भी सक्षम होना चाहिए (यदि भुगतान 3-D Secure कॉन्फ़िगरेशन त्रुटि के साथ विफल हों, तो Braintree सहायता से संपर्क करें)।

कार्ड से शुल्क लेने से पहले 3-D Secure का परिणाम केवल ब्राउज़र में नहीं, बल्कि सर्वर पर भी जाँचा जाता है।

उन्नत

Debug log: API कॉल और भुगतान के चरण मॉड्यूल फ़ोल्डर में logs/wc_btg_debug.log.php में भी लॉग होते हैं। यह फ़ाइल वेब से नहीं खोली जा सकती। यह बंद हो तब भी त्रुटियाँ हमेशा लॉग होती हैं। लॉग में कभी API कुंजियाँ, कार्ड या ग्राहक का डेटा नहीं होता। डिफ़ॉल्ट: off।

Log: लॉग का आकार और नवीनतम प्रविष्टियाँ दिखाता है। उसे खाली करने के लिए Clear log पर क्लिक करें।

Delete data on uninstall: चालू होने पर मॉड्यूल हटाने से गेटवे सेटिंग्स और लॉग हट जाते हैं। Braintree लेन-देन, रिफ़ंड और ऑर्डर स्थितियाँ हमेशा रहती हैं, इसलिए पहले भुगतान किए गए ऑर्डर फिर से इंस्टॉल करने के बाद भी रिफ़ंड, कैप्चर या void किए जा सकते हैं। डिफ़ॉल्ट: off।

चेकआउट

भुगतान के चरण में ग्राहक भुगतान विधि चुनता है (डिफ़ॉल्ट रूप से Credit / debit card) और भुगतान विकल्प के भीतर Braintree फ़ॉर्म में कार्ड दर्ज करता है। यह फ़ॉर्म केवल चेकआउट पेज पर Braintree से लोड होता है और स्टोर की भाषा का उपयोग करता है। 3-D Secure चालू होने पर ग्राहक ऑर्डर देते समय बैंक का सत्यापन पूरा करता है; कार्ट का कुल योग, ईमेल और बिलिंग पता इस सत्यापन को भेजे जाते हैं।

इसके बाद मॉड्यूल एक बार उपयोग होने वाले टोकन पर, कार्ट की मुद्रा में, कार्ट के कुल योग का शुल्क Braintree API के माध्यम से लेता है, और Braintree में ऑर्डर ID के रूप में कार्ट नंबर का उपयोग करता है। इस बिंदु से पहले कोई ऑर्डर मौजूद नहीं होता। चार्ज की गई राशि और मुद्रा की कार्ट से तुलना होती है। ऑर्डर तभी बनता है जब Braintree भुगतान स्वीकार कर ले, और ग्राहक को PrestaShop का मानक ऑर्डर पुष्टि पेज दिखता है।

यदि भुगतान विफल होता है, तो कोई ऑर्डर नहीं बनता, कारण मॉड्यूल लॉग में लिखा जाता है, और ग्राहक एक संदेश के साथ भुगतान चरण पर रहता है, उदाहरण के लिए Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. या The card security code or billing address could not be verified. Please check your details and try again. ग्राहक तुरंत फिर से प्रयास कर सकता है। यदि चार्ज की गई मुद्रा या राशि कार्ट से मेल नहीं खाती, तो लेन-देन void हो जाता है और ग्राहक को This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us. दिखता है।

एक कार्ट से दोबारा चार्ज कभी नहीं होता। भुगतान चलते समय दूसरी बार सबमिट करने पर This order is already being paid. Please wait a moment and check your e-mail before trying again. दिखता है। यदि कार्ड से शुल्क ले लिया गया, पर PrestaShop ऑर्डर नहीं बना सका, तो ग्राहक को Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. दिखता है। उसी कार्ट के लिए अगला प्रयास सेव किए गए लेन-देन से ऑर्डर बनाता है, बिना दोबारा चार्ज किए।

मॉड्यूल केवल कार्ड से भुगतान लेता है। इसमें सेव किए गए कार्ड, सब्सक्रिप्शन या आवर्ती भुगतान नहीं हैं, और PayPal, Venmo, Apple Pay, Google Pay या स्थानीय भुगतान विधियाँ नहीं हैं, और Braintree वेबहुक का उपयोग नहीं होता।

ऑर्डर और रिफ़ंड

ऑर्डर स्थितियाँ

अभी कोई ऑर्डर नहीं: भुगतान नहीं हुआ या अस्वीकृत हुआ। केवल कार्ट मौजूद है।

Payment accepted: कार्ड से शुल्क लिया गया (Sale), या एक प्राधिकरण कैप्चर किया गया। भुगतान Braintree लेन-देन ID के साथ दर्ज होता है, और ऑर्डर के संदेशों में एक निजी नोट राशि, लेन-देन ID और 3-D Secure परिणाम दिखाता है।

Braintree payment authorized: राशि केवल प्राधिकृत है (Authorize only)। जब तक आप उसे कैप्चर नहीं करते, कोई भुगतान दर्ज नहीं होता।

Braintree payment on hold: Braintree ने अप्रत्याशित लेन-देन स्थिति लौटाई, या गलत मुद्रा या राशि वाला चार्ज अपने-आप void नहीं हो सका। नोट बताता है कि Braintree Control Panel में क्या जाँचना है।

Canceled: एक प्राधिकरण void किया गया।

Refunded: मॉड्यूल के माध्यम से भुगतान पूरी तरह रिफ़ंड किया गया।

यदि पहले से बने ऑर्डर के लिए कोई और लेन-देन आता है, तो ऑर्डर नहीं बदलता। एक नोट आपसे उसे Braintree Control Panel में जाँचने और void या रिफ़ंड करने को कहता है।

Braintree payment ब्लॉक

ऑर्डर पेज पर एक Braintree payment ब्लॉक दिखता है, जिसमें लेन-देन ID (उसके वातावरण के Braintree Control Panel में लेन-देन से लिंक), लेन-देन की स्थिति, राशि और मर्चेंट खाता, 3-D Secure परिणाम, चार्ज और रिफ़ंड की गई राशि, सैंडबॉक्स भुगतानों के लिए Sandbox बैज, और रिफ़ंड का इतिहास शामिल है। ब्लॉक के बटनों के लिए ऑर्डर संपादित करने का अधिकार चाहिए; Modules पेज तक पहुँच की ज़रूरत नहीं है।

कैप्चर और void

Braintree payment authorized स्थिति वाले ऑर्डर के लिए, ऑर्डर का कुल योग चार्ज करने हेतु Capture Braintree payment पर क्लिक करें, या रोकी गई राशि छोड़ने हेतु Void Braintree authorization पर क्लिक करें। कैप्चर ऑर्डर को Payment accepted पर सेट करता है और भुगतान दर्ज करता है; void उसे Canceled पर सेट करता है। यदि कार्रवाई विफल होती है, तो त्रुटि ब्लॉक में दिखती है और ऑर्डर नोट्स में जोड़ी जाती है।

रिफ़ंड

Braintree payment ब्लॉक में राशि दर्ज करें (जो राशि अभी रिफ़ंड नहीं हुई, वह अपने-आप भर जाती है), वैकल्पिक रूप से कारण लिखें, और Refund via Braintree पर क्लिक करें। प्रश्न Refund this amount through Braintree? This cannot be undone. की पुष्टि करें। पूर्ण और आंशिक दोनों रिफ़ंड समर्थित हैं। रिफ़ंड उसी राशि और मुद्रा में होते हैं जो Braintree ने चार्ज की थी, इसलिए राशि या मुद्रा में अंतर होने पर आप अधिकतम उतनी राशि रिफ़ंड कर सकते हैं जितनी ग्राहक ने वास्तव में चुकाई थी। Braintree केवल सेटल हो चुके लेन-देन रिफ़ंड करता है, आमतौर पर 24 घंटों के भीतर। सेटलमेंट से पहले पूर्ण रिफ़ंड void के रूप में होता है; आंशिक रिफ़ंड तब इस संदेश के साथ विफल होता है कि सेटलमेंट की प्रतीक्षा करें। रिफ़ंड भुगतान के वातावरण (सैंडबॉक्स या लाइव) में भेजा जाता है, इसलिए उस वातावरण के क्रेडेंशियल सेट होने चाहिए। यदि Braintree रिफ़ंड स्वीकार नहीं करता, तो ब्लॉक त्रुटि दिखाता है और कोई रिफ़ंड दर्ज नहीं होता। सफल रिफ़ंड रिफ़ंड इतिहास और नोट्स में जुड़ता है। पूर्ण रिफ़ंड ऑर्डर को Refunded पर सेट करता है; आंशिक रिफ़ंड स्थिति नहीं बदलता।

मॉड्यूल क्रेडिट स्लिप नहीं बनाता। ऑर्डर पेज के PrestaShop के मानक रिफ़ंड बटन Braintree के माध्यम से पैसा वापस नहीं भेजते। विवाद (chargebacks), सेटलमेंट में अस्वीकृत भुगतान और Braintree Control Panel में किए गए रिफ़ंड PrestaShop के साथ सिंक नहीं होते।

लाइसेंस कुंजी

यह मॉड्यूल vibefox.net से प्राप्त VibeFox लाइसेंस कुंजी के साथ काम करता है। लाइसेंस ब्लॉक License — VibeFox Braintree Gateway, Modules > Module Manager > VibeFox Braintree Gateway > Configure पर सेटिंग्स के ऊपर पहला ब्लॉक है। कुंजी को License key में चिपकाएँ और Activate पर क्लिक करें। इसके बाद ब्लॉक कुंजी को मास्क करके दिखाता है, साथ में स्थिति (जैसे वह तारीख जब तक लाइसेंस सक्रिय है और आपका डोमेन), और ये बटन: स्थिति दोबारा जाँचने के लिए Check now, दूसरी कुंजी दर्ज करने के लिए Change key, और इस शॉप से कुंजी हटाने के लिए Remove key। उनके नीचे Product: presta-payment-braintree वाली पंक्ति और Manage licenses and domains in your account लिंक है, जो आपका vibefox.net खाता खोलता है। केवल उन कर्मचारियों को कुंजी बदलने की अनुमति है जिनके पास इस मॉड्यूल के लिए Configure अनुमति है। ब्लॉक के टेक्स्ट बैक ऑफ़िस की भाषा का पालन करते हैं (अंग्रेज़ी और रूसी शामिल हैं)।

यदि कुंजी स्वीकार नहीं होती, तो ब्लॉक कारण बताता है, जैसे Key not found, This key belongs to another product, Domain limit reached या तारीख के साथ License expired on। शॉप का पता बदलने के बाद, या अपने खाते में डोमेन स्लॉट खाली करने के बाद, Check now पर क्लिक करें। यदि लाइसेंस सर्वर तक पहुँच न हो, तो मॉड्यूल अंतिम ज्ञात स्थिति के आधार पर काम करता रहता है।

एक कुंजी एक ही डोमेन पर काम करती है: मुख्य शॉप के डोमेन पर, मल्टीस्टोर सेटअप में भी। शॉप से कुंजी हटाने से उसका डोमेन स्लॉट खाली नहीं होता। अपने vibefox.net खाते में स्लॉट खाली करें।

सक्रिय कुंजी के बिना चेकआउट पर ग्राहकों को Braintree नहीं दिखाया जाता। यदि फिर भी भुगतान शुरू होता है, तो ग्राहक को This payment method is not available. Please choose another one. दिखता है। PrestaShop स्टोरफ़्रंट को पता नहीं होता कि आप बैक ऑफ़िस में लॉग इन हैं, इसलिए भुगतान विधि आपसे भी छिपी रहती है: आप कुंजी खरीदने से पहले मॉड्यूल सेट कर सकते हैं, पर चेकआउट पर उसका परीक्षण नहीं कर सकते। Modules > Module Manager में Alerts टैब पर एक अनुस्मारक दिखता है। मौजूदा ऑर्डर प्रभावित नहीं होते: पहले से शुरू किए गए भुगतानों की पुष्टि होती रहती है, और कैप्चर, void और रिफ़ंड काम करते हैं।

लाइसेंस समाप्त होने पर मॉड्यूल काम करता रहता है, पर अपडेट और सपोर्ट के लिए नवीनीकरण चाहिए। बैक ऑफ़िस में काम करते समय स्थिति अपने-आप दोबारा जाँची जाती है: कुंजी दर्ज करने के बाद पहले 14 दिनों में रोज़ एक बार, फिर हर हफ़्ते एक बार। कोई cron job ज़रूरी नहीं है। मॉड्यूल अनइंस्टॉल करने या रीसेट करने पर लाइसेंस कुंजी और लाइसेंस स्थिति हमेशा हटा दी जाती हैं।

समस्या निवारण

चेकआउट पर Braintree दिखाई नहीं देता: जाँचें कि लाइसेंस सक्रिय है, Enable/Disable चालू है, और चुने गए वातावरण में Merchant ID, Public Key और Private Key मौजूद हैं। कोई कुंजी न होने पर सेटिंग्स पेज चेतावनी दिखाता है। Payment > Preferences में जाँचें कि मॉड्यूल कार्ट की मुद्रा, ग्राहक के देश और ग्राहक समूह के लिए अनुमत है।

कार्ड से शुल्क लिया गया, पर कोई ऑर्डर नहीं बना: कार्ड भुगतान वेबहुक के बिना तुरंत पुष्ट होते हैं। मॉड्यूल पेज पर Log फ़ील्ड देखें। यदि लॉग कहता है कि Braintree का उत्तर खो गया, तो कोई और भुगतान स्वीकार करने से पहले Braintree Control Panel में ऐसा लेन-देन जाँचें जिसमें ऑर्डर ID के रूप में कार्ट नंबर हो। यदि शुल्क के बाद ऑर्डर नहीं बन सका, तो उसी कार्ट के लिए अगला भुगतान प्रयास उसे बिना दोबारा चार्ज किए बना देगा।

कार्ड फ़ॉर्म में Could not initialize payment form दिखता है: चुने गए वातावरण की कुंजियाँ गलत हैं, या उस खाते में मर्चेंट खाता ID मौजूद नहीं है। कुंजियाँ और मर्चेंट खाता ID जाँचें, फिर पेज रीलोड करें।

हर भुगतान पर 3-D Secure विफल होता है: आपके Braintree मर्चेंट खाते के लिए 3-D Secure सक्षम होना चाहिए। Braintree सहायता से संपर्क करें, या 3-D Secure को Disabled पर सेट करें (EEA और UK में इसकी सिफ़ारिश नहीं है, जहाँ SCA अनिवार्य है)।

ग्राहक को बताया जाता है कि भुगतान ऑर्डर की मुद्रा में प्रोसेस नहीं हो सका: Braintree ने मर्चेंट खाते की मुद्रा में चार्ज किया। वर्तमान वातावरण के मर्चेंट खाता फ़ील्ड में कार्ट की मुद्रा के लिए मर्चेंट खाता ID दर्ज करें।

ग्राहक को The order total must be greater than zero to pay by card दिखता है: कार्ट का कुल योग शून्य है, उदाहरण के लिए वाउचर लगाने के बाद। ऐसे ऑर्डर कार्ड से नहीं चुकाए जा सकते।

भुगतान के ठीक बाद आंशिक रिफ़ंड विफल होता है: Braintree केवल सेटल हो चुके लेन-देन रिफ़ंड कर सकता है, आमतौर पर 24 घंटों के भीतर। अभी लेन-देन void करने के लिए पूरी राशि रिफ़ंड करें, या सेटलमेंट के बाद आंशिक रिफ़ंड करें।

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

अनइंस्टॉल

Modules > Module Manager पर जाएँ, VibeFox Braintree Gateway के बगल का मेनू खोलें और Uninstall चुनें। इस मॉड्यूल की लाइसेंस कुंजी और लाइसेंस स्थिति हमेशा हटा दी जाती हैं। यदि Delete data on uninstall चालू है, तो गेटवे सेटिंग्स और लॉग हटा दिए जाते हैं। यदि यह बंद है, तो बाद में फिर से इंस्टॉल करने के लिए सभी सेटिंग्स रखी जाती हैं। Braintree लेन-देन और रिफ़ंड तथा ऑर्डर स्थितियाँ Braintree payment authorized और Braintree payment on hold हमेशा रखे जाते हैं, इसलिए पहले भुगतान किए गए ऑर्डर फिर से इंस्टॉल करने के बाद भी रिफ़ंड, कैप्चर या void किए जा सकते हैं। मौजूदा ऑर्डर अपने भुगतान नोट्स और लेन-देन ID बनाए रखते हैं।

Braintree उसके संबंधित स्वामी का ट्रेडमार्क है। यह मॉड्यूल Braintree से संबद्ध नहीं है और न ही Braintree द्वारा समर्थित है।