VibeFox Kushki for WooCommerce — सहायता

आवश्यकताएँ

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

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

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

स्टोर की मुद्रा: USD (इक्वाडोर) या COP (कोलंबिया)। अन्य मुद्राओं में चेकआउट पर यह भुगतान विकल्प छिपा दिया जाता है।

HTTPS: Kushki के अनुसार लाइव मोड में चेकआउट HTTPS पर उपलब्ध होना चाहिए।

Kushki खाता: आपको अपने Kushki टेस्ट (UAT) खाते और प्रोडक्शन खाते के Public और Private Merchant ID चाहिए। ये Kushki Console में Developers > Credentials के अंतर्गत मिलते हैं। वैकल्पिक वेबहुक के लिए आपको हर खाते की वेबहुक हस्ताक्षर कुंजी भी चाहिए (देखें कॉन्फ़िगरेशन)।

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

इंस्टॉलेशन

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

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

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

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

5. टेस्ट के लिए Public और Private Merchant ID डालें और Test mode चालू रखें। वैकल्पिक रूप से, Kushki Console में वेबहुक सेट करें और उसकी हस्ताक्षर कुंजी चिपकाएँ (देखें कॉन्फ़िगरेशन)।

6. Enable / Disable चालू करें और एक टेस्ट ऑर्डर दें। तैयार होने पर लाइव Merchant ID (और लाइव वेबहुक हस्ताक्षर) डालें और Test mode का चेक हटा दें।

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

सभी सेटिंग्स एक ही पेज पर हैं: WooCommerce > Settings > Payments > Kushki। फ़ील्ड्स के ऊपर पेज चेतावनी देता है जब भुगतान विकल्प चालू हो पर वर्तमान मोड के Merchant ID नहीं हैं (तब यह भुगतान विकल्प चेकआउट पर छिपा रहता है), जब स्टोर की मुद्रा समर्थित न हो, जब लाइव मोड बिना HTTPS के इस्तेमाल हो रहा हो, और जब वर्तमान मोड में वेबहुक हस्ताक्षर न हो। जब तक टेस्ट मोड चालू है, यह Test mode is on: the Kushki test environment is used, no real money is charged. दिखाता है। यदि भुगतान विकल्प चालू है पर वर्तमान मोड के Merchant ID नहीं डाले गए हैं और आप सेव करते हैं, तो उन्हें डालने की याद दिलाने वाली त्रुटि दिखती है। ID के आगे-पीछे के स्पेस सेव करते समय हटा दिए जाते हैं।

सामान्य

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

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

Description: चेकआउट पर कार्ड फ़ॉर्म के ऊपर दिखने वाला पाठ। डिफ़ॉल्ट: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

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

Kushki Console (Developers > Credentials) से Public और Private Merchant ID कॉपी करें। टेस्ट (UAT) और प्रोडक्शन खातों के ID अलग होते हैं। टेस्ट मोड केवल टेस्ट ID इस्तेमाल करता है, और लाइव मोड केवल लाइव ID।

Test mode: Use the Kushki test (UAT) environment Merchant ID, कार्ड फ़ॉर्म और API को एक साथ Kushki टेस्ट वातावरण में बदल देता है। कोई असली पैसा नहीं लिया जाता, और चेकआउट पर TEST MODE बैज दिखता है। डिफ़ॉल्ट: चालू। असली भुगतान लेने के लिए इसका चेक हटाएँ।

Test Public Merchant ID: आपके Kushki टेस्ट खाते का Public Merchant ID। यह कार्ड फ़ॉर्म लोड करता है।

Test Private Merchant ID: आपके Kushki टेस्ट खाते का Private Merchant ID। यह सर्वर पर शुल्क और रिफ़ंड के लिए इस्तेमाल होता है।

Live Public Merchant ID: आपके Kushki प्रोडक्शन खाते का Public Merchant ID।

Live Private Merchant ID: आपके Kushki प्रोडक्शन खाते का Private Merchant ID। इसे गुप्त रखें।

वेबहुक (अनुशंसित)

भुगतान Kushki API के उत्तर से तुरंत पुष्ट हो जाते हैं, इसलिए वेबहुक आवश्यक नहीं है। यह उन भुगतानों की भी पुष्टि करता है जिनका उत्तर खो गया हो (जैसे टाइमआउट पर), और Kushki Console में किए गए रद्दीकरण और रिफ़ंड की सूचना देता है। Kushki Console (Webhooks) में कार्ड भुगतानों के लिए, सेटिंग्स के इस भाग में दिखाया गया URL जोड़ें। यह कुछ ऐसा दिखता है: https://your-site/wc-api/webhook_kushki_p/। यह टेस्ट खाते और प्रोडक्शन खाते दोनों के लिए करें।

प्लगइन ये कार्ड सूचनाएँ संभालता है:

Test webhook signature: Kushki टेस्ट खाते की वेबहुक हस्ताक्षर कुंजी (Console > Webhooks)।

Live webhook signature: Kushki प्रोडक्शन खाते की वेबहुक हस्ताक्षर कुंजी।

वैध हस्ताक्षर के बिना वेबहुक अस्वीकार कर दिए जाते हैं। हस्ताक्षर कुंजी के बिना सभी वेबहुक सूचनाएँ अस्वीकार होती हैं, लेकिन भुगतान फिर भी काम करते हैं, क्योंकि वे API उत्तर से पुष्ट होते हैं।

उन्नत

Debug log: Log API calls and webhooks Kushki के अनुरोध और वेबहुक WooCommerce > Status > Logs में, स्रोत wcp_kushki_payment के तहत लिखता है। त्रुटियाँ हमेशा दर्ज होती हैं। लॉग में कभी भी Merchant ID, कार्ड टोकन या ग्राहक के ईमेल नहीं होते। डिफ़ॉल्ट: बंद।

Delete data on uninstall: चालू होने पर प्लगइन हटाने से सेटिंग्स और लॉग हट जाते हैं। ऑर्डर और उनके Kushki संदर्भ सुरक्षित रहते हैं। डिफ़ॉल्ट: बंद।

चेकआउट

ग्राहक भुगतान विकल्प चुनता है (डिफ़ॉल्ट रूप से Credit / debit card (Kushki))। उसके नीचे Kushki का कार्ड फ़ॉर्म दिखता है, जिसमें ऑर्डर की मुद्रा में ऑर्डर का कुल दिखता है। Pay for order पेज पर फ़ॉर्म ऑर्डर का कुल इस्तेमाल करता है। ग्राहक कार्ड डालता है, यदि Kushki फ़ॉर्म किस्तें देता है तो किस्त चुनता है, और Kushki फ़ॉर्म के भीतर भुगतान बटन दबाता है।

क्लासिक चेकआउट पर, जब तक Kushki चुना है तब तक WooCommerce का Place order बटन छिपा रहता है: कार्ड स्वीकार होने के बाद ऑर्डर अपने-आप जमा हो जाता है। चेकआउट ब्लॉक पर ग्राहक को भी Kushki फ़ॉर्म के भीतर भुगतान बटन दबाना होता है। यदि ग्राहक बिना ऐसा किए ऑर्डर देने की कोशिश करता है, तो यह संदेश दिखता है: Please enter your card details in the Kushki form and press its pay button.

इसके बाद आपका स्टोर सर्वर पर कार्ड से शुल्क लेता है। ऑर्डर तभी भुगतान किया हुआ माना जाता है जब Kushki उसे टिकट नंबर के साथ पुष्ट करे, और ग्राहक सीधे ऑर्डर प्राप्त होने वाले पेज पर जाता है। यदि Kushki स्वीकृत राशि या मुद्रा बताता है, तो उसकी तुलना ऑर्डर से की जाती है।

यदि कार्ड अस्वीकार होता है, तो ग्राहक को Kushki से मिले कारण के साथ Your payment was declined दिखता है, और वह उसी फ़ॉर्म में दूसरा कार्ड आज़मा सकता है। नेटवर्क, कुंजी या सर्वर की समस्या होने पर ग्राहक को The payment could not be processed right now. Please try again in a moment or choose another payment method. दिखता है। तकनीकी कारण ऑर्डर नोट्स और लॉग में जोड़ा जाता है। भुगतान प्रक्रिया के दौरान दूसरी बार क्लिक करने पर A payment for this order is already being processed. Please wait a moment and check your order status. दिखता है।

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

प्लगइन केवल एक-चरण वाले कार्ड भुगतान लेता है। इसमें आंशिक रिफ़ंड, सेव किए गए कार्ड, सब्सक्रिप्शन या Add payment method नहीं हैं, और नकद, बैंक ट्रांसफ़र (PSE) या डेबिट-कार्ड रीडायरेक्ट भुगतान नहीं हैं। ऑथराइज़ और कैप्चर अलग-अलग भी नहीं होते।

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

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

Pending payment: ऑर्डर बन गया है, और कार्ड से अभी शुल्क नहीं लिया गया है।

Processing: Kushki ने शुल्क की पुष्टि कर दी है (API उत्तर या वेबहुक से)। केवल डाउनलोड होने वाले वर्चुअल उत्पादों वाले ऑर्डर WooCommerce के डिफ़ॉल्ट के अनुसार Completed हो जाते हैं। ऑर्डर नोट में मोड, Kushki टिकट नंबर और संदर्भ दिखते हैं। ट्रांज़ैक्शन ID Kushki का ट्रांज़ैक्शन संदर्भ (या टिकट नंबर) है।

On hold: Kushki ने बिना टिकट नंबर के सफलता लौटाई, या ऑर्डर से अलग राशि या मुद्रा बताई। ऑर्डर नोट इसका कारण समझाता है। Kushki Console में ट्रांज़ैक्शन जाँचें, फिर ऑर्डर पूरा करें या भुगतान रिफ़ंड करें।

Failed: कार्ड अस्वीकार हुआ या शुल्क नहीं लिया जा सका। ऑर्डर नोट में Kushki का कोड और संदेश दिखता है। ग्राहक फिर से भुगतान कर सकता है।

यदि कोई वेबहुक पहले से भुगतान किए गए, रद्द हुए या रिफ़ंड हुए ऑर्डर के लिए एक और स्वीकृत शुल्क बताता है, तो ऑर्डर नहीं बदला जाता। एक नोट आपसे दोहरे शुल्क की जाँच करने और Kushki Console में रिफ़ंड करने को कहता है। लाइव ऑर्डर के लिए टेस्ट वातावरण का वेबहुक (या इसका उल्टा) नोट के साथ अनदेखा किया जाता है।

रिफ़ंड

ऑर्डर खोलें, Refund पर क्लिक करें, ऑर्डर का पूरा कुल डालें और Refund via Credit / debit card (Kushki) पर क्लिक करें (बटन पर आपका Title दिखता है)। Kushki पूरा भुगतान रिफ़ंड करता है, इसलिए केवल पूर्ण रिफ़ंड स्वीकार किए जाते हैं। आंशिक राशि के लिए प्लगइन यह दिखाता है: Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. एक भुगतान एक ही बार रिफ़ंड किया जा सकता है।

रिफ़ंड उसी मोड में भेजा जाता है जिसमें भुगतान हुआ था (टेस्ट या लाइव), इसलिए उस मोड का Private Merchant ID सेट होना चाहिए। यदि Kushki रिफ़ंड स्वीकार नहीं करता, तो WooCommerce त्रुटि दिखाता है और कोई रिफ़ंड दर्ज नहीं होता। सफल रिफ़ंड Kushki रिफ़ंड टिकट के साथ ऑर्डर नोट्स में जोड़ा जाता है।

Kushki Console में किए गए रद्दीकरण और रिफ़ंड वेबहुक से आते हैं और ऑर्डर नोट्स में जोड़े जाते हैं। उन्हें अपने-आप WooCommerce रिफ़ंड के रूप में दर्ज नहीं किया जाता।

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

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

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

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

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

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

चेकआउट पर Kushki नहीं दिखता: जाँचें कि लाइसेंस सक्रिय है, Enable / Disable चालू है और वर्तमान मोड में दोनों Merchant ID हैं: टेस्ट मोड में टेस्ट ID, लाइव मोड में लाइव ID। जाँचें कि स्टोर की मुद्रा (या Pay for order पेज पर ऑर्डर की मुद्रा) USD या COP है। सेटिंग्स पेज इनमें से हर समस्या के लिए चेतावनी दिखाता है।

भुगतान हो गया, लेकिन ऑर्डर Failed है या Pending payment पर अटका है: टाइमआउट जैसे कारणों से Kushki API का उत्तर खो गया। वेबहुक ऐसे भुगतानों की पुष्टि करता है। Kushki Console में जाँचें कि वेबहुक URL सेटिंग्स में दिखाए गए URL से हूबहू मेल खाता है, आप जिस मोड का उपयोग कर रहे हैं उसके खाते के लिए है, और उस खाते की हस्ताक्षर कुंजी सही फ़ील्ड (Test webhook signature या Live webhook signature) में है। बिना भुगतान की गई राशि और मुद्रा वाला स्वीकृत शुल्क इसके बजाय ऑर्डर को होल्ड पर रख देता है।

वेबहुक Webhook signature not configured का उत्तर देता है: कोई वेबहुक हस्ताक्षर सेट नहीं है। सेटिंग्स में हस्ताक्षर कुंजी चिपकाएँ।

वेबहुक Invalid signature का उत्तर देता है: हस्ताक्षर कुंजी किसी दूसरे खाते या मोड की है, या रास्ते में सूचना बदल दी गई।

वेबहुक Order mismatch का उत्तर देता है: सूचना इस ऑर्डर की नहीं है (गलत ऑर्डर कुंजी या ट्रांज़ैक्शन)। ऑर्डर नहीं बदला जाता।

वेबहुक Busy, retry later का उत्तर देता है: उसी समय कोई दूसरा अनुरोध इस ऑर्डर को प्रोसेस कर रहा था। Kushki सूचना फिर से भेज सकता है।

कार्ड फ़ॉर्म लोड नहीं होता: ग्राहक को The Kushki card form could not be loaded. Please reload the page or choose another payment method. दिखता है। वर्तमान मोड का Public Merchant ID जाँचें।

ग्राहक को This payment option is not available in this store. Please pay by card. दिखता है: Kushki फ़ॉर्म में कार्ड के अलावा कोई भुगतान विकल्प चुना गया। प्लगइन केवल कार्ड से शुल्क लेता है।

ग्राहक को भुगतान करते समय त्रुटि दिखती है: ऑर्डर नोट्स खोलें या Debug log चालू करके WooCommerce > Status > Logs में स्रोत wcp_kushki_payment देखें। गलत या गायब Private Merchant ID से भुगतान प्रोसेस न हो पाने का सामान्य संदेश दिखता है।

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

No Kushki ticket number found for this order संदेश के साथ रिफ़ंड विफल: इस ऑर्डर का कोई पुष्ट Kushki शुल्क नहीं है। Kushki Console में रिफ़ंड करें।

अन्य मुद्राएँ: डेवलपर kushki_p_supported_currencies फ़िल्टर से मुद्रा सूची बदल सकते हैं, लेकिन अपने जोखिम पर। वह मुद्रा आपके Kushki खाते में सक्षम होनी चाहिए।

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

अनइंस्टॉल

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

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