VibeFox Pesapal for PrestaShop — सहायता

आवश्यकताएँ

PrestaShop: 8.0 से 9.x।

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

मुद्रा: कार्ट KES, UGX, TZS, ZMW, RWF या USD में होना चाहिए। अन्य मुद्राओं में चेकआउट पर भुगतान का तरीका नहीं दिखता। कार्ट का शुल्क उसकी अपनी मुद्रा में लिया जाता है; मॉड्यूल मुद्रा रूपांतरण नहीं करता। राशियाँ मुख्य इकाइयों में भेजी जाती हैं, जो मुद्रा की सटीकता के अनुसार पूर्णांकित होती हैं (UGX और RWF में दशमलव नहीं होते)।

Pesapal खाता: आपको Pesapal मर्चेंट खाते की कंज़्यूमर कुंजी और कंज़्यूमर सीक्रेट चाहिए। सैंडबॉक्स और लाइव कुंजियाँ अलग-अलग होती हैं। सैंडबॉक्स कुंजियाँ cybqa.pesapal.com पर डेमो मर्चेंट खाते से मिलती हैं (Pesapal अपने डेवलपर पोर्टल पर भी डेमो कुंजियाँ प्रकाशित करता है)। लाइव कुंजियाँ आपके Pesapal मर्चेंट डैशबोर्ड से मिलती हैं। Pesapal डैशबोर्ड में और कुछ सेट करने की ज़रूरत नहीं है: मॉड्यूल अपनी सूचना URL स्वयं पंजीकृत करता है। आपकी साइट इंटरनेट से पहुँच योग्य होनी चाहिए, क्योंकि Pesapal उसे भुगतान सूचनाएँ भेजता है।

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

इंस्टॉलेशन

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

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

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

4. सैंडबॉक्स कंज़्यूमर कुंजी और सीक्रेट दर्ज करें, Enable/Disable चालू करें, Save पर क्लिक करें और एक टेस्ट ऑर्डर करें।

5. लाइव कंज़्यूमर कुंजी और सीक्रेट दर्ज करें, Sandbox mode बंद करें और असली भुगतान स्वीकार करने के लिए Save पर क्लिक करें।

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

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

सभी सेटिंग्स मॉड्यूल पेज पर हैं: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure। हर सेक्शन का अपना Save बटन है, जो पूरा पेज सेव करता है। फ़ील्ड के ऊपर एक बैज मोड दिखाता है: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. या LIVE — Real payments on pay.pesapal.com. जब मौजूदा मोड की कुंजियाँ न हों (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., या लाइव के लिए वही संदेश), और जब Pesapal आपके स्टोर की डिफ़ॉल्ट मुद्रा का समर्थन न करे, तब चेतावनी दिखती है।

Pesapal

Enable/Disable: Enable Pesapal भुगतान का तरीका चालू या बंद करता है। डिफ़ॉल्ट: बंद।

Title: वह नाम जो ग्राहक चेकआउट पर भुगतान के तरीके के रूप में देखते हैं। यही नाम ऑर्डर में भुगतान के तरीके के रूप में सेव होता है। डिफ़ॉल्ट: Pesapal (M-Pesa, Airtel Money, cards)। अनिवार्य: खाली शीर्षक सेव नहीं होता, पिछला शीर्षक रहता है।

Description: चेकआउट पर भुगतान के तरीके के नीचे दिखने वाला पाठ। डिफ़ॉल्ट: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

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

यह सेक्शन बताता है कि कुंजियाँ कहाँ से मिलेंगी, और cybqa.pesapal.com व pesapal.com के लिंक देता है। सैंडबॉक्स और लाइव कुंजियाँ अलग-अलग फ़ील्ड में दर्ज करें।

Sandbox mode: Use the Pesapal sandbox (no real money)। चालू होने पर नए भुगतान सैंडबॉक्स कुंजियों के साथ cybqa.pesapal.com पर होते हैं। असली भुगतान लाइव कुंजियों के साथ pay.pesapal.com पर स्वीकार करने के लिए इसे बंद करें। डिफ़ॉल्ट: चालू।

Sandbox consumer key: आपके सैंडबॉक्स (डेमो) मर्चेंट खाते की कंज़्यूमर कुंजी। केवल सैंडबॉक्स मोड में उपयोग होती है।

Sandbox consumer secret: आपके सैंडबॉक्स मर्चेंट खाते का कंज़्यूमर सीक्रेट। केवल सैंडबॉक्स मोड में उपयोग होता है।

Live consumer key: आपके Pesapal मर्चेंट डैशबोर्ड की कंज़्यूमर कुंजी। तब उपयोग होती है जब सैंडबॉक्स मोड बंद हो।

Live consumer secret: आपके Pesapal मर्चेंट डैशबोर्ड का कंज़्यूमर सीक्रेट। तब उपयोग होता है जब सैंडबॉक्स मोड बंद हो।

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

Clear saved consumer keys and secrets: चेकबॉक्स चुनें और सेव किए गए चारों कुंजी व सीक्रेट हटाने के लिए Save पर क्लिक करें।

सेटिंग्स सेव करने पर कैश किए गए Pesapal एक्सेस टोकन हटा दिए जाते हैं। मोड बदलने या कुंजियाँ बदलने से दूसरे मोड या दूसरी कुंजियों का एक्सेस टोकन या सूचना ID कभी दोबारा इस्तेमाल नहीं होता। किसी एक मोड में शुरू हुए भुगतान की जाँच हमेशा उसी मोड में होती है, मोड बदलने के बाद भी।

भुगतान सूचनाएँ (IPN)

IPN URL: आपके स्टोर की सूचना URL दिखाता है। फ़्रेंडली URL के साथ यह कुछ इस तरह दिखता है: https://your-shop/module/wcp_pesapal_pay/webhook, संभवतः /en/ जैसे भाषा कोड के साथ। यह URL पहले भुगतान पर Pesapal में अपने-आप पंजीकृत होता है, सैंडबॉक्स और लाइव के लिए अलग-अलग तथा हर कुंजी-जोड़े के लिए, इसलिए कुछ सेट करने की ज़रूरत नहीं है। पहले भुगतान के बाद यह सेक्शन Pesapal द्वारा लौटाई गई ID के साथ Registered IPN ID: दिखाता है; उससे पहले यह Not registered yet for the current mode and keys. दिखाता है। यह URL इंटरनेट से पहुँच योग्य होना चाहिए: इसके सामने कोई फ़ायरवॉल या पासवर्ड सुरक्षा नहीं होनी चाहिए। स्टोर मेंटेनेंस मोड में होने पर भी यह काम करता रहता है और आपके स्टोर की देश-सीमा से बाधित नहीं होता।

एडवांस्ड

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

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

Delete data: Delete the module settings and logs when the module is uninstalled। ऑर्डरों पर सेव Pesapal डेटा (ट्रैकिंग ID, नोट) भुगतान इतिहास है और हमेशा रखा जाता है। मॉड्यूल बंद करने से कुछ नहीं मिटता। डिफ़ॉल्ट: बंद।

चेकआउट

भुगतान के चरण पर ग्राहक भुगतान का तरीका चुनता है (डिफ़ॉल्ट रूप से Pesapal (M-Pesa, Airtel Money, cards)) और उसका विवरण देखता है। पुष्टि करने पर मॉड्यूल कार्ट के कुल योग के लिए, कार्ट की मुद्रा में, बिलिंग पते के बिलिंग विवरण के साथ एक Pesapal भुगतान अनुरोध बनाता है और ग्राहक को Pesapal के भुगतान पेज पर भेज देता है। Pesapal को भेजा गया भुगतान विवरण Cart, कार्ट नंबर और स्टोर का नाम है। वहाँ ग्राहक Pesapal द्वारा दिए गए तरीकों में से किसी एक से भुगतान करता है, जैसे M-Pesa, Airtel Money, MTN, कार्ड या बैंक। इस बिंदु पर अभी कोई ऑर्डर नहीं होता।

ऑर्डर तभी भुगतान किया हुआ चिह्नित होता है जब Pesapal उसकी पुष्टि कर दे। Pesapal की सूचनाओं और ग्राहक की वापसी में न भुगतान डेटा होता है, न हस्ताक्षर; इसलिए मॉड्यूल उन पर भरोसा नहीं करता: हर एक के लिए वह उसी मोड में, जिसमें भुगतान शुरू हुआ था, प्रमाणित सर्वर-से-सर्वर अनुरोध से Pesapal से लेन-देन की स्थिति पूछता है। वह यह भी जाँचता है कि लेन-देन इसी कार्ट का है, और भुगतान की गई राशि व मुद्रा कार्ट से मेल खाती है। इसके बाद ऑर्डर बनता है और ग्राहक को मानक ऑर्डर पुष्टि पेज दिखता है।

मोबाइल मनी भुगतान में कुछ समय लग सकता है। यदि ग्राहक के लौटने तक Pesapal ने भुगतान की पुष्टि नहीं की है, तो एक Payment confirmation पेज दिखता है, जिस पर लिखा होता है Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again., और साथ में Check again और Back to checkout बटन होते हैं। Pesapal की सूचना भुगतान की पुष्टि होते ही ऑर्डर बना देती है। यदि ऑर्डर होल्ड पर रखा गया हो, तो पुष्टि पेज पर दिखता है Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

यदि ग्राहक Pesapal पेज पर रद्द कर देता है, तो वह The Pesapal payment was cancelled. You can try again or choose another payment method. संदेश के साथ चेकआउट पर लौट आता है। यदि भुगतान विफल हो जाता है, तो संदेश है The Pesapal payment was not successful. Please try again or choose another payment method. कार्ट बना रहता है और ग्राहक दोबारा भुगतान कर सकता है। कार्ट का हर भुगतान प्रयास याद रखा जाता है, इसलिए कार्ट के किसी पुराने Pesapal पेज पर बाद में किया गया भुगतान भी स्वीकार होता है।

यदि Pesapal भुगतान शुरू नहीं कर पाता, तो ग्राहक एक छोटे संदेश के साथ चेकआउट पर रहता है, उदाहरण के लिए Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (गलत कुंजियाँ), या Pesapal could not start the payment: के बाद Pesapal से मिला कारण। तकनीकी कारण लॉग में लिखा जाता है। ऑर्डर का कुल योग शून्य से अधिक होना चाहिए।

मॉड्यूल में आपकी अपनी साइट पर कोई भुगतान फ़ॉर्म नहीं है (ग्राहक हमेशा Pesapal के पेज पर भुगतान करता है), न सेव किए गए कार्ड, न सब्सक्रिप्शन या आवर्ती भुगतान, और न ही मुद्रा रूपांतरण।

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

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

अभी कोई ऑर्डर नहीं: ग्राहक को Pesapal पर भेजा गया था और उसने भुगतान नहीं किया, भुगतान विफल हुआ, या Pesapal ने अभी भुगतान की पुष्टि नहीं की। केवल कार्ट मौजूद है।

Payment accepted: Pesapal भुगतान को पूरा हुआ बताता है और राशि व मुद्रा मेल खाती हैं। भुगतान Pesapal ट्रैकिंग ID को लेन-देन ID के रूप में दर्ज होता है, और एक नोट में राशि, भुगतान का तरीका, Pesapal पुष्टि कोड और ट्रैकिंग ID दिखते हैं। हर भुगतान केवल एक बार लागू होता है।

Pesapal payment on hold: भुगतान की गई राशि या मुद्रा कार्ट से अलग है (नोट Pesapal amount/currency mismatch — held for review), या रद्द किए गए ऑर्डर के लिए पैसे आए हैं। वास्तव में भुगतान की गई राशि ऑर्डर पर दर्ज होती है, जब वह ऑर्डर की मुद्रा में हो। Pesapal डैशबोर्ड में भुगतान की जाँच करें, फिर ऑर्डर पूरा करें या भुगतान रिफ़ंड करें।

Refunded: Pesapal बताता है कि जिस भुगतान से ऑर्डर चुकाया गया था, वह रिवर्स हो गया है। किसी दूसरे प्रयास का रिवर्सल केवल ऑर्डर पर नोट होता है।

यदि पहले से भुगतान किए गए कार्ट का दूसरा भुगतान प्रयास भी पूरा हो जाता है, तो ऑर्डर नहीं बदलता। एक नोट आपसे कहता है कि दूसरा भुगतान Pesapal डैशबोर्ड में रिफ़ंड करें। रद्द और रिफ़ंड किए गए ऑर्डर अपने-आप दोबारा नहीं खुलते।

Pesapal भुगतान ब्लॉक

ऑर्डर पेज पर एक Pesapal payment ब्लॉक दिखता है, जिसमें Sandbox या Live बैज, ट्रैकिंग ID, मर्चेंट संदर्भ, Pesapal स्थिति, भुगतान का तरीका, पुष्टि कोड, अनुरोधित व भुगतान की गई राशि, समीक्षा का कारण, कार्ट के सभी Payment attempts और ऑर्डर के Payment notes होते हैं। यह ब्लॉक केवल पढ़ने के लिए है।

रिफ़ंड

मॉड्यूल Pesapal को रिफ़ंड नहीं भेजता। Pesapal डैशबोर्ड में भुगतान रिफ़ंड करें, फिर PrestaShop में रिफ़ंड को मैन्युअल रूप से दर्ज करें।

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

मॉड्यूल vibefox.net से मिली VibeFox लाइसेंस कुंजी से काम करता है। लाइसेंस ब्लॉक License — VibeFox Pesapal Pay Gateway मॉड्यूल के Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure पेज पर सेटिंग्स से ऊपर पहला ब्लॉक है। कुंजी License key में दर्ज करें और Activate पर क्लिक करें। इसके बाद ब्लॉक में कुंजी छिपी हुई (मास्क की हुई) दिखती है, स्थिति (जैसे वह तारीख जिस तक लाइसेंस सक्रिय है, और आपका डोमेन) दिखती है, और ये बटन दिखते हैं: Check now स्थिति दोबारा जाँचने के लिए, Change key दूसरी कुंजी दर्ज करने के लिए और Remove key इस स्टोर से कुंजी हटाने के लिए। इनके नीचे Product: presta-payment-pesapal वाली पंक्ति और 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 खाते में खाली करें।

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

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

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

चेकआउट पर Pesapal नहीं दिखता: जाँचें कि लाइसेंस सक्रिय है, Enable/Disable चालू है, मौजूदा मोड की कंज़्यूमर कुंजी और सीक्रेट दर्ज हैं (सैंडबॉक्स मोड में Sandbox consumer key और Sandbox consumer secret, लाइव मोड में Live consumer key और Live consumer secret) और कार्ट की मुद्रा KES, UGX, TZS, ZMW, RWF या USD है। सेटिंग्स के शीर्ष की चेतावनियाँ समस्या बताती हैं। Payment > Preferences में जाँचें कि मॉड्यूल कार्ट की मुद्रा, ग्राहक के देश और ग्राहक समूह के लिए अनुमत है। डेवलपर actionPesapalSupportedCurrencies हुक से मुद्राओं की सूची बदल सकते हैं।

भुगतान हो गया, पर ऑर्डर नहीं बना: Pesapal की सूचना आपके स्टोर तक नहीं पहुँची और ग्राहक वापस नहीं आया। जाँचें कि IPN URL में दिखाया गया URL इंटरनेट से पहुँच योग्य है (इसके सामने कोई फ़ायरवॉल या पासवर्ड सुरक्षा नहीं होनी चाहिए)। Debug log चालू करें और मॉड्यूल पेज पर Log फ़ील्ड देखें।

स्टोर सूचनाओं का जवाब कैसे देता है: संसाधित सूचना को HTTP 200 से उत्तर मिलता है। यदि मॉड्यूल उसे संसाधित नहीं कर पाता, तो वह त्रुटि से उत्तर देता है, और Pesapal सूचना बाद में फिर भेजता है: 400 (ट्रैकिंग ID नहीं है या गलत रूप में है), 404 (इस स्टोर के किसी कार्ट में यह ट्रैकिंग ID नहीं है), 409 (लेन-देन किसी दूसरे मर्चेंट संदर्भ का है; कुछ नहीं बदला जाता), 502 (उस समय Pesapal API तक पहुँच नहीं हो सकी, या जिस मोड में भुगतान शुरू हुआ था उसकी कुंजियाँ नहीं हैं) और 503 (ग्राहक की वापसी से कार्ट उसी समय अपडेट हो रहा था, या ऑर्डर नहीं बन सका, उदाहरण के लिए मॉड्यूल बंद होने के कारण)।

ग्राहक को Pesapal is not available at the moment दिखता है: Pesapal ने मौजूदा मोड की कंज़्यूमर कुंजी या सीक्रेट अस्वीकार कर दिया। जाँचें कि कुंजियाँ मोड के अनुसार हैं: सैंडबॉक्स कुंजियाँ केवल सैंडबॉक्स में चलती हैं, लाइव कुंजियाँ केवल लाइव मोड में। लॉग में Pesapal की त्रुटि दिखती है।

ग्राहक को Pesapal is temporarily unavailable दिखता है: Pesapal तक पहुँच नहीं हो सकी, या सूचना URL पंजीकृत नहीं हो सका। लॉग पढ़ें और फिर से प्रयास करें।

मोड बदलने के बाद पुराने मोड के भुगतान पुष्ट नहीं हो रहे: भुगतान की जाँच उसी मोड की कुंजियों से होती है, जिसमें वह शुरू हुआ था। उस मोड की कुंजियाँ तब तक दर्ज रहने दें जब तक उसके भुगतान पुष्ट न हो जाएँ।

भुगतान के बाद ऑर्डर Pesapal payment on hold में है: Pesapal payment ब्लॉक के नोट पढ़ें। भुगतान की गई राशि या मुद्रा कार्ट से अलग थी, या भुगतान ऑर्डर रद्द होने के बाद आया। Pesapal डैशबोर्ड में भुगतान की जाँच करें, फिर ऑर्डर संसाधित करें या भुगतान रिफ़ंड करें।

अनइंस्टॉल

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

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