VibeFox Pagar.me for WooCommerce — सहायता

आवश्यकताएँ

WordPress: 6.0 या उसके बाद का संस्करण।

WooCommerce: 8.0 या उसके बाद का संस्करण, स्थापित और सक्रिय। इसके बिना प्लगइन सक्रिय नहीं होता।

PHP: 8.0 या उसके बाद का संस्करण।

मुद्रा: Brazilian Real (BRL)। यदि स्टोर की मुद्रा (या Pay for order पेज पर ऑर्डर की मुद्रा) BRL नहीं है, तो भुगतान विधि छिप जाती है।

Pagar.me खाता: आपको अपने Pagar.me खाते की सीक्रेट कुंजियाँ चाहिए: टेस्ट कुंजी (sk_test_...) और लाइव पर जाने के लिए लाइव कुंजी (sk_...)। ये Pagar.me डैशबोर्ड में Development > Keys के अंतर्गत मिलती हैं। केवल सीक्रेट कुंजियाँ उपयोग होती हैं; पब्लिक कुंजी (pk_...) की ज़रूरत नहीं है। केवल वही भुगतान विधियाँ दी जा सकती हैं जो आपके Pagar.me खाते में सक्षम हों।

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

इंस्टॉलेशन

1. WordPress में Plugins > Add New > Upload Plugin पर जाएँ, प्लगइन की ZIP फ़ाइल चुनें और Install Now पर क्लिक करें। आप FTP से wcp_pagarme_gateway फ़ोल्डर को /wp-content/plugins/ में भी अपलोड कर सकते हैं।

2. Activate पर क्लिक करें।

3. सेटिंग्स खोलें: WooCommerce > Settings > Payments > Pagar.me > Manage, या Plugins पेज पर प्लगइन के नाम के नीचे Settings पर क्लिक करें।

4. पेज के ऊपर लाइसेंस ब्लॉक में अपनी VibeFox लाइसेंस कुंजी डालें और Activate पर क्लिक करें।

5. टेस्ट सीक्रेट कुंजी डालें और लाइव होने पर लाइव सीक्रेट कुंजी डालें।

6. Pagar.me डैशबोर्ड में सेटिंग्स में दिखाए गए URL के साथ वेबहुक बनाएँ (देखें कॉन्फ़िगरेशन)।

7. Enable / Disable चालू करें और सेव करें। Test mode चालू रखकर टेस्ट भुगतान करें, फिर असली भुगतान लेने के लिए उसे बंद करें।

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

सभी सेटिंग्स एक ही पेज पर हैं: WooCommerce > Settings > Payments > Pagar.me। शीर्षक के नीचे पेज वर्तमान मोड दिखाता है: TEST MODE (भुगतान टेस्ट सीक्रेट कुंजी से बनते हैं, कोई असली शुल्क नहीं लगता) या LIVE। यह चेतावनी देता है जब वर्तमान मोड की सीक्रेट कुंजी नहीं है (तब चेकआउट पर भुगतान विधि छिपी रहती है), जब टेस्ट कुंजी sk_test_ से शुरू नहीं होती, जब लाइव कुंजी sk_ से शुरू नहीं होती या टेस्ट कुंजी है, और जब स्टोर की मुद्रा BRL नहीं है। भुगतान विधियों की सूची में Pagar.me तब तक सेटअप की ज़रूरत वाला दिखता है जब तक वर्तमान मोड की कुंजी डाली न जाए, और टेस्ट मोड चालू होने पर टेस्ट मोड बैज दिखता है।

सामान्य

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

Title: वह भुगतान विधि का नाम जो ग्राहक चेकआउट पर देखते हैं। डिफ़ॉल्ट: Pagar.me।

Description: चेकआउट पर भुगतान विधि के नीचे दिखने वाला पाठ। डिफ़ॉल्ट: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API कुंजियाँ

Pagar.me डैशबोर्ड से सीक्रेट कुंजियाँ कॉपी करें: Development > Keys। Pagar.me टेस्ट और लाइव भुगतान के लिए एक ही API पता इस्तेमाल करता है; भुगतान टेस्ट है या असली, यह कुंजी तय करती है।

Test mode: Use the test secret key (no real charges)। टेस्ट मोड चालू होने पर चेकआउट पर TEST MODE नोट दिखता है। किसी ऑर्डर की स्थिति की जाँच और रिफ़ंड हमेशा उसी मोड की कुंजी से होते हैं जिसमें उसका भुगतान बना था। डिफ़ॉल्ट: चालू।

Test secret key: Pagar.me की टेस्ट सीक्रेट कुंजी (sk_test_...)। टेस्ट मोड चालू होने पर इसका उपयोग होता है।

Live secret key: Pagar.me की लाइव सीक्रेट कुंजी (sk_...)। टेस्ट मोड बंद होने पर इसका उपयोग होता है। इसे गोपनीय रखें।

संस्करण 1.0 की एकल सीक्रेट कुंजी अपने-आप स्थानांतरित हो जाती है: टेस्ट कुंजी Test secret key में चली जाती है और टेस्ट मोड चालू हो जाता है; अन्यथा वह लाइव कुंजी ही रहती है और टेस्ट मोड बंद हो जाता है।

भुगतान पेज

Payment methods: Pagar.me भुगतान पेज पर दी जाने वाली विधियाँ। केवल वही चुनें जो आपके Pagar.me खाते में सक्षम हों। डिफ़ॉल्ट: Credit card, PIX और Boleto।

Boleto due in (days): boleto की देय तिथि तक के दिन, 1 से 30 के बीच। Pagar.me के भुगतान की पुष्टि करने तक ऑर्डर On hold रहता है। डिफ़ॉल्ट: 3।

भुगतान सूचनाएँ (वेबहुक)

Pagar.me डैशबोर्ड में Settings > Webhooks खोलें और इस सेक्शन में दिखाए गए URL के साथ वेबहुक बनाएँ। यह कुछ इस तरह दिखता है: https://your-site/wc-api/webhook_wc_pagarme/। इसे ठीक वैसे ही कॉपी करें जैसा सेटिंग्स में दिखाया गया है।

ये इवेंट चुनें:

वेबहुक को पासवर्ड या सिग्नेचर की ज़रूरत नहीं होती। इसकी सामग्री पर कभी भरोसा नहीं किया जाता: स्टोर उससे केवल Pagar.me ऑर्डर ID लेता है और उस ऑर्डर को उसी मोड की कुंजी से Pagar.me API से पढ़ता है जिसमें वह बना था। उसी Pagar.me खाते के अन्य स्टोर्स के ऑर्डर की सूचनाएँ अनदेखी की जाती हैं। वेबहुक के बिना, बाद में किए गए PIX और boleto भुगतान तभी पुष्ट होते हैं जब ग्राहक स्टोर पर वापस आता है।

उन्नत

Debug log: Log API requests and notifications विवरण WooCommerce > Status > Logs में, स्रोत wcp_pagarme_gateway के रूप में लिखता है। त्रुटियाँ हमेशा दर्ज होती हैं। लॉग में कुंजियाँ या ग्राहक डेटा नहीं होते। डिफ़ॉल्ट: बंद।

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted। डिफ़ॉल्ट: बंद।

चेकआउट

ग्राहक भुगतान विधि चुनता है (डिफ़ॉल्ट रूप से Pagar.me) और ऑर्डर देता है। एक वैध बिलिंग ईमेल आवश्यक है। प्लगइन ऑर्डर कुल के लिए BRL में एक Pagar.me ऑर्डर बनाता है, जिसमें ऑर्डर लाइनें, शिपिंग और शुल्क शामिल होते हैं (या यदि लाइनें ठीक-ठीक नहीं जुड़ सकतीं, तो ऑर्डर नंबर वाली एक Order # लाइन), और ग्राहक को Pagar.me के भुगतान पेज पर भेजता है। ग्राहक का नाम, ईमेल और, ब्राज़ील के लिए, फ़ोन नंबर तथा बिलिंग पता Pagar.me को दिए जाते हैं। CPF या CNPJ, यदि मौजूद हों तो Brazilian Market on WooCommerce प्लगइन के फ़ील्ड्स से लिए जाते हैं; अन्यथा ग्राहक उसे Pagar.me पेज पर दर्ज करता है।

भुगतान के बाद ग्राहक आपके स्टोर पर लौटता है। ऑर्डर केवल तभी भुगतान किया हुआ चिह्नित होता है जब Pagar.me उसकी पुष्टि कर दे: स्टोर API से Pagar.me ऑर्डर पढ़ता है, और भुगतान की गई राशि तथा मुद्रा ऑर्डर से मेल खानी चाहिए। भुगतान किया गया कार्ड, PIX या boleto ऑर्डर को भुगतान किया हुआ चिह्नित करता है। जारी हुआ लेकिन अभी तक न चुकाया गया PIX या boleto ऑर्डर को तब तक On hold रखता है जब तक Pagar.me वेबहुक से भुगतान की पुष्टि न कर दे।

यदि ग्राहक बिना भुगतान किए लौटता है, या भुगतान अस्वीकार या रद्द हो गया, तो ग्राहक Pay for order पेज पर जाता है, जहाँ The Pagar.me payment was not completed. You can pay the order below. या The Pagar.me payment was declined or canceled. You can try again below. लिखा होता है।

जब ग्राहक दोबारा भुगतान करता है, तो खुला Pagar.me भुगतान पेज दोबारा उपयोग होता है, यदि राशि और मोड समान हों; अन्यथा नया बनाने से पहले उसे Pagar.me पर बंद कर दिया जाता है। यदि इस बीच पिछले प्रयास का भुगतान हो चुका है, या उसका PIX या boleto अभी भी प्रतीक्षा में है, तो बिना नए भुगतान के ऑर्डर अपडेट हो जाता है। यदि पिछला पेज बंद नहीं किया जा सकता, तो वह ऑर्डर से जुड़ा रहता है, ताकि उस पर किया गया भुगतान फिर भी दर्ज हो।

यदि Pagar.me भुगतान शुरू नहीं कर पाता, तो ग्राहक को एक संक्षिप्त संदेश दिखता है, जैसे Could not connect to Pagar.me. Please try again in a moment., या बिलिंग विवरण अमान्य होने पर Pagar.me का संदेश। तकनीकी कारण ऑर्डर नोट्स में जोड़ दिया जाता है।

यह भुगतान विधि क्लासिक चेकआउट, Checkout ब्लॉक और Pay for order पेज पर काम करती है। यह WooCommerce High-Performance Order Storage (HPOS) के साथ संगत है।

इस प्लगइन में आपके चेकआउट में कार्ड फ़ॉर्म नहीं है, न सेव किए गए कार्ड, सब्सक्रिप्शन या आवर्ती भुगतान, न इंस्टॉलमेंट नियम, न स्प्लिट भुगतान (मार्केटप्लेस), न केवल-ऑथराइज़ेशन कार्ड भुगतान, और न ही Pagar.me Hub का एकीकरण।

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

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

Pending payment: ग्राहक को Pagar.me पर भेजा गया है और उसने अभी भुगतान नहीं किया है या PIX या boleto जारी नहीं हुआ है। एक नोट में Pagar.me ऑर्डर ID और मोड दिखता है।

Processing: भुगतान की पुष्टि हो गई है। यह भुगतान के बाद WooCommerce की मानक स्थिति है; केवल डाउनलोड योग्य वर्चुअल उत्पादों वाले ऑर्डर Completed हो जाते हैं। ऑर्डर नोट में Pagar.me ऑर्डर ID और भुगतान विधि दिखती है। ट्रांज़ैक्शन ID Pagar.me ऑर्डर ID (or_...) है।

On hold: PIX या boleto जारी हुआ है (या कार्ड भुगतान समीक्षा में है) और भुगतान की प्रतीक्षा है; या boleto केवल आंशिक रूप से चुकाया गया है; या भुगतान की गई राशि या मुद्रा ऑर्डर से अलग है; या ऑर्डर रद्द होने के बाद भुगतान आया; या ग्राहक द्वारा भुगतान विधि बदलने के बाद Pagar.me पर ऑर्डर का भुगतान हुआ; या भुगतान किए गए ऑर्डर पर चार्जबैक खुला। ऑर्डर नोट इसका कारण बताता है। ऑर्डर की समीक्षा करें और उसे Processing पर सेट करें, या Pagar.me पर भुगतान रिफ़ंड करें।

Failed: भुगतान विफल हुआ, या Pagar.me ऑर्डर रद्द हो गया या समाप्त हो गया (जैसे बिना चुकाया गया boleto)। केवल बिना भुगतान वाले ऑर्डर का नवीनतम प्रयास ही उसे Failed कर सकता है। ग्राहक फिर से भुगतान कर सकता है।

Refunded: Pagar.me पर भुगतान रिफ़ंड या रद्द हो गया।

हर Pagar.me स्थिति एक ही बार लागू होती है, इसलिए दोहराए गए वेबहुक या वापसी से नोट, ईमेल या स्टॉक में कमी नहीं जुड़ती। भुगतान किया हुआ ऑर्डर कभी वापस pending या failed नहीं होता, और रद्द या रिफ़ंड किया गया ऑर्डर कभी दोबारा नहीं खुलता। यदि उसी WooCommerce ऑर्डर का दूसरा Pagar.me ऑर्डर भुगतान हो जाता है, तो एक नोट आपसे Pagar.me डैशबोर्ड में डुप्लिकेट का रिफ़ंड करने को कहता है।

रिफ़ंड

ऑर्डर खोलें, Refund पर क्लिक करें, राशि दर्ज करें और Refund via Pagar.me पर क्लिक करें (बटन पर आपकी भुगतान विधि का शीर्षक दिखता है)। कार्ड और PIX भुगतानों के पूर्ण और आंशिक रिफ़ंड समर्थित हैं, उस राशि तक जो Pagar.me पर अभी भी रिफ़ंड की जा सकती है। रिफ़ंड उसी मोड की कुंजी से भेजा जाता है जिसमें भुगतान हुआ था। रिफ़ंड केवल तभी दर्ज होता है जब Pagar.me उसकी पुष्टि करे; अन्यथा WooCommerce त्रुटि दिखाता है, जैसे Pagar.me refused the refund: ... या Pagar.me did not confirm the refund, और कोई रिफ़ंड दर्ज नहीं होता। सफल रिफ़ंड चार्ज ID के साथ ऑर्डर नोट्स में जुड़ जाता है।

Boleto भुगतान केवल ग्राहक के बैंक खाते में रिफ़ंड किए जा सकते हैं। उन्हें Pagar.me डैशबोर्ड में रिफ़ंड करें, फिर Refund via Pagar.me का उपयोग किए बिना WooCommerce में रिफ़ंड मैन्युअली दर्ज करें।

Pagar.me डैशबोर्ड में किया गया पूर्ण रिफ़ंड या रद्दीकरण वेबहुक से आता है और ऑर्डर को Refunded पर सेट करता है। चार्जबैक एक नोट जोड़ता है और Processing या Completed ऑर्डर को On hold कर देता है।

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

यह प्लगइन vibefox.net से मिली VibeFox लाइसेंस कुंजी के साथ काम करता है। लाइसेंस ब्लॉक WooCommerce > Settings > Payments > Pagar.me के ऊपर होता है। कुंजी को License key में चिपकाएँ और Activate पर क्लिक करें। ब्लॉक स्थिति दिखाता है, जैसे लाइसेंस किस तारीख तक सक्रिय है और आपका डोमेन। स्थिति दोबारा जाँचने के लिए Check now, दूसरी कुंजी डालने के लिए Change key और इस साइट से कुंजी हटाने के लिए Remove key इस्तेमाल करें। Manage licenses and domains in your account लिंक आपका vibefox.net खाता खोलता है।

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

सक्रिय कुंजी के बिना चेकआउट पर Pagar.me ग्राहकों को नहीं दिखता। फिर भी भुगतान शुरू हो जाए, तो ग्राहक को This payment method is not available. Please choose another one. दिखता है। लॉग इन किए हुए स्टोर मैनेजरों को भुगतान विधि (unlicensed — visible to admins only) चिह्न के साथ दिखती रहती है, ताकि आप कुंजी खरीदने से पहले प्लगइन सेट अप और टेस्ट कर सकें। प्लगइन पेज और WooCommerce पेजों पर एक अनुस्मारक दिखता है। मौजूदा ऑर्डर प्रभावित नहीं होते: पहले से शुरू हो चुके भुगतान अब भी पुष्ट होते हैं, और रिफ़ंड भी काम करते हैं।

लाइसेंस की समय-सीमा खत्म होने पर प्लगइन चलता रहता है, लेकिन अपडेट और सहायता के लिए नवीनीकरण ज़रूरी है। स्थिति पृष्ठभूमि में अपने-आप फिर से जाँची जाती है।

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

चेकआउट पर Pagar.me नहीं दिखता: जाँचें कि लाइसेंस सक्रिय है, Enable / Disable चालू है, वर्तमान मोड की सीक्रेट कुंजी (टेस्ट मोड में Test secret key, लाइव मोड में Live secret key) डाली गई है और स्टोर की मुद्रा BRL है। सेटिंग्स पेज हर स्थिति में चेतावनी दिखाता है।

भुगतान हो गया, पर ऑर्डर Pending payment या On hold पर अटका है: वेबहुक ठीक से काम नहीं कर रहा। Pagar.me डैशबोर्ड में जाँचें कि आपके खाते और मोड के लिए वेबहुक मौजूद है, उसका URL सेटिंग्स में दिखाए गए URL से बिल्कुल मेल खाता है, और ऊपर सूचीबद्ध इवेंट चुने गए हैं। ग्राहक के स्टोर पर लौटने पर भी ऑर्डर की जाँच होती है।

वेबहुक verification failed, retry later का उत्तर देता है: स्टोर API से Pagar.me ऑर्डर नहीं पढ़ सका, जैसे उस मोड की कुंजी न होना या API का उत्तर न देना। Pagar.me वेबहुक को दोबारा भेजता है।

वेबहुक busy, retry later का उत्तर देता है: उसी समय किसी दूसरे अनुरोध से ऑर्डर अपडेट हो रहा था। Pagar.me वेबहुक को दोबारा भेजता है।

वेबहुक unknown order का उत्तर देता है: वह Pagar.me ऑर्डर इस स्टोर ने नहीं बनाया, जैसे उसी खाते की किसी दूसरी दुकान का ऑर्डर। कुछ नहीं बदला जाता।

ग्राहक को This order is already being processed दिखता है: कोई वेबहुक या ग्राहक की वापसी उसी समय ऑर्डर अपडेट कर रही थी। ग्राहक थोड़ी देर बाद फिर प्रयास कर सकता है।

ग्राहक को Pagar.me payments are not available right now दिखता है: सीक्रेट कुंजी गलत है या गायब है। वर्तमान मोड की कुंजी जाँचें।

ग्राहक को Pagar.me could not start the payment दिखता है: Pagar.me ने बिलिंग विवरण अस्वीकार किए। संदेश समस्या बताता है; पूरा कारण ऑर्डर नोट्स में है।

ग्राहक को Pagar.me only supports payments in Brazilian Real (BRL) दिखता है: ऑर्डर किसी अन्य मुद्रा में है, जैसे मुद्रा बदलने वाले प्लगइन के कारण।

भुगतान के बाद ऑर्डर On hold है: ऑर्डर नोट पढ़ें। PIX या boleto भुगतान की प्रतीक्षा में है, भुगतान की गई राशि या मुद्रा अलग थी, या ऑर्डर रद्द होने के बाद भुगतान आया।

boleto के लिए रिफ़ंड विफल होता है: boleto भुगतान API से रिफ़ंड नहीं किए जा सकते। Pagar.me डैशबोर्ड में रिफ़ंड करें और उसे मैन्युअली दर्ज करें।

लाइसेंस ब्लॉक में त्रुटि दिखती है: ब्लॉक का संदेश देखें। उदाहरण के लिए, यदि कुंजी किसी दूसरे डोमेन पर पहले से इस्तेमाल हो रही है, तो अपने vibefox.net खाते में स्लॉट मुक्त करें और Check now पर क्लिक करें। यदि साइट का पता बदल गया है, तो नए डोमेन के लिए कुंजी सक्रिय करने हेतु Check now पर क्लिक करें। यदि लाइसेंस सर्वर तक पहुँच नहीं है, तो प्लगइन आखिरी ज्ञात स्थिति पर चलता रहता है।

अनइंस्टॉल

प्लगइन निष्क्रिय करने पर सारा डेटा सुरक्षित रहता है। इसे हटाने के लिए Plugins पेज पर इसे निष्क्रिय करके हटाएँ। इस प्लगइन की लाइसेंस कुंजी और लाइसेंस स्थिति हमेशा हटाई जाती है। गेटवे सेटिंग्स और प्लगइन के लॉग केवल तभी हटते हैं जब Delete data on uninstall चालू था। अन्यथा वे बाद में दोबारा इंस्टॉल करने के लिए रहते हैं। मौजूदा ऑर्डर अपने भुगतान नोट, ट्रांज़ैक्शन ID और Pagar.me डेटा रखते हैं।

Pagar.me उसके संबंधित स्वामी का ट्रेडमार्क है। यह प्लगइन Pagar.me से संबद्ध नहीं है और Pagar.me द्वारा अनुमोदित नहीं है।