Square Terminal गेटवे

Square Terminal गेटवे आपको WCPOS से सीधे Square Terminal हार्डवेयर पर WooCommerce ऑर्डर भुगतान स्वीकार करने देता है। भुगतान WooCommerce से अनुरोध किया जाता है और जोड़े गए Square Terminal डिवाइस पर पूरा होता है, फिर परिणाम ऑर्डर में वापस लिखा जाता है।

विशेषताएँ

हार्डवेयर एकीकरण

जोड़े गए Square Terminal डिवाइसों पर भुगतान भेजें और कार्ड-प्रेजेंट भुगतान स्वीकार करें

एक-क्लिक कनेक्ट

सीधे Square से अधिकृत करें — कोई एक्सेस टोकन बनाने या चिपकाने की आवश्यकता नहीं

भरोसेमंद पूर्णता

भुगतान पोलिंग और एक पृष्ठभूमि स्वीपर द्वारा पुष्ट किए जाते हैं, और webhooks इसे तेज़ बनाते हैं

सुरक्षित लेनदेन

Square हार्डवेयर पर संभाली जाने वाली PCI-अनुपालक, कार्ड-प्रेजेंट प्रोसेसिंग

सैंडबॉक्स और उत्पादन

लाइव भुगतान पर जाने से पहले Square सैंडबॉक्स में सत्यापन करें

यह कैसे काम करता है

ब्राउज़र-SDK गेटवे के विपरीत, Square Terminal Square की server-side Terminal API का उपयोग करता है। जब आप भुगतान शुरू करते हैं, WooCommerce ऑर्डर के लिए एक Terminal Checkout बनाता है और Square उसे जोड़े गए डिवाइस पर भेजता है। ग्राहक टर्मिनल पर भुगतान करता है, और परिणाम ऑर्डर में वापस लिखा जाता है।

भुगतान की पुष्टि कैसे होती है। भुगतान चलने के दौरान POS Square को पोल करता रहता है, और एक पृष्ठभूमि स्वीपर उन सभी मामलों का मिलान कर लेता है जो पोल से छूट जाते हैं — जैसे बंद कर दिया गया ब्राउज़र टैब। Square webhooks एक वैकल्पिक जोड़ हैं जो प्रतीक्षा कम करते हैं; वे आवश्यक नहीं हैं, और उनके बिना भी किसी साइट का कोई भुगतान कभी नहीं खोता।

Square Terminal डिवाइस ऑनलाइन होना चाहिए और प्लगइन के समान ही Square खाते और location में साइन इन होना चाहिए।

सेटअप

1

Square Terminal for WooCommerce स्थापित करें

WP Admin > POS > Settings > Extensions से स्थापित करें, या GitHub releases page से नवीनतम plugin zip asset डाउनलोड करें (GitHub source-code zip या tarball नहीं) और उसे Plugins > Add New > Upload Plugin के माध्यम से अपलोड करें।

2

Square से कनेक्ट करें

1. WP Admin > WooCommerce > Settings > Payments पर जाएँ और Square Terminal खोलें
2. Square account के अंतर्गत, Environment चुनें — परीक्षण के लिए Sandbox, लाइव भुगतान के लिए Production
3. Connect to Square पर क्लिक करें और Square द्वारा दिखाई गई अनुमतियाँ स्वीकृत करें
4. Location ID चुनें — वह Square location जिसके लिए Terminal भुगतान लेता है

environment को कनेक्ट करने से पहले चुनें। एक कनेक्शन केवल एक ही environment को कवर करता है; सैंडबॉक्स कनेक्शन कभी भी उत्पादन भुगतान को अधिकृत नहीं कर सकता।

क्या आप पहले से आधिकारिक WooCommerce Square प्लगइन उपयोग कर रहे हैं?

Environment और Location ID उसकी सेटिंग्स से पहले से भर दिए जाते हैं। केवल यही दो मान पढ़े जाते हैं — प्लगइनों के बीच कोई क्रेडेंशियल साझा नहीं होते, और आपको यहाँ फिर भी कनेक्ट करना होगा या एक्सेस टोकन देना होगा।

अपना खुद का एक्सेस टोकन उपयोग करना चाहते हैं?

Advanced settings खोलें और कनेक्ट करने के बजाय चयनित environment के लिए एक एक्सेस टोकन चिपकाएँ। बाकी सब कुछ बिल्कुल वैसा ही काम करता है।

3

अपना Square Terminal पेयर करें

Terminal के अंतर्गत:

1. Create Device Code पर क्लिक करें — एक पेयरिंग कोड दिखाई देता है
2. Square Terminal पर, डिवाइस-कोड साइन-इन स्क्रीन खोलें और कोड दर्ज करें। यदि Terminal इस समय Square POS या किसी अन्य इंटीग्रेशन में साइन इन है, तो पहले उससे साइन आउट करें — जब तक वह कहीं और उपयोग में है, डिवाइस-कोड स्क्रीन तक नहीं पहुँचा जा सकता।
3. यह पुष्टि करने के लिए Check for readers पर क्लिक करें कि वह अब Paired with this plugin के अंतर्गत दिखाई देता है

पेयरिंग से पहले सूची का खाली होना अपेक्षित है, कोई खराबी नहीं। Square का device API केवल उन्हीं Terminals की जानकारी देता है जो Terminal API उपयोग के लिए सेट किए गए हैं — Square POS चला रहा Terminal तब तक बिल्कुल दिखाई नहीं देता जब तक उस पर कोई डिवाइस कोड दर्ज न किया जाए।

4

WCPOS में सक्षम करें

1. WP Admin > POS > Settings > Checkout पर जाएँ
2. Square Terminal गेटवे खोजें और उसे POS के लिए सक्षम करें
3. अपनी सेटिंग्स सहेजें

नोट

WooCommerce सेटिंग्स स्क्रीन पर Enable/Disable चेकबॉक्स केवल ऑनलाइन स्टोर चेकआउट को नियंत्रित करता है। कॉन्फ़िगर हो जाने के बाद WCPOS इस गेटवे का उपयोग स्वतः करता है, चाहे वह बॉक्स चेक हो या नहीं।

Terminal पेयर करना

कैशियर द्वारा चुने जा सकने से पहले Square Terminal को इस प्लगइन के साथ पेयर करना आवश्यक है। पेयरिंग एक Terminal API Device Code बनाती है, और प्लगइन केवल उसी के ज़रिए डिवाइस तक पहुँच सकता है।

सेटिंग्स स्क्रीन पर Terminal के अंतर्गत:

• Create Device Code — Terminal पर दर्ज करने के लिए एक कोड बनाता है। यह थोड़े समय के लिए ही मान्य होता है; समाप्त हो जाने पर नया बनाएँ।
• Check for readers — Square को जो दिखता है उसे दो समूहों में सूचीबद्ध करता है:
  • Paired with this plugin — चेकआउट पर चुना जा सकता है
  • Other devices Square can see at this location — किसी अन्य एप्लिकेशन द्वारा सेट किए गए, इसलिए इस प्लगइन के साथ पेयर होने तक यहाँ नहीं चुने जा सकते
• Validate Settings — क्रेडेंशियल और location को Square के विरुद्ध जाँचता है

आपका अपना Terminal क्यों चुना नहीं जा सकता

Device Codes उसी एप्लिकेशन के होते हैं जिसने उन्हें बनाया है, इसलिए किसी अन्य Terminal API इंटीग्रेशन द्वारा सेट किया गया Terminal Other devices Square can see के अंतर्गत दिखता है लेकिन यहाँ चुना नहीं जा सकता। Square POS चला रहा Terminal बिल्कुल दिखाई ही नहीं देता।

दोनों ही स्थितियों में समाधान एक ही है: Terminal को जिस भी चीज़ से वह पेयर है उससे साइन आउट करें, फिर यहाँ एक नया Create Device Code दर्ज करें।

Webhooks

Webhooks वैकल्पिक हैं। वे केवल यह कम करते हैं कि किसी भुगतान की पुष्टि में कितना समय लगता है। पोलिंग और पृष्ठभूमि स्वीपर हर भुगतान की पुष्टि वैसे भी कर देते हैं, इसलिए बिना webhook सब्सक्रिप्शन वाली साइट भी सही ढंग से काम करती है — बस निपटान में थोड़ा अधिक समय लगता है।

यदि आपने Connect to Square उपयोग किया है तो उपलब्ध नहीं

Webhook सब्सक्रिप्शन किसी Square एप्लिकेशन का होता है, और उसे जोड़ने के लिए Square Developer Dashboard में उस एप्लिकेशन तक पहुँच आवश्यक है। यदि आपने Connect to Square से कनेक्ट किया है, तो आप अपने किसी एप्लिकेशन के बजाय WCPOS एप्लिकेशन को अधिकृत कर रहे हैं, इसलिए आपके लिए न तो सब्सक्रिप्शन जोड़ने वाला कोई डैशबोर्ड है और न ही कॉपी करने के लिए कोई सिग्नेचर कुंजी।

भुगतान फिर भी सामान्य रूप से पुष्ट होते हैं — पोलिंग और स्वीपर द्वारा। नीचे दिए गए चरण केवल तभी लागू होते हैं जब आपने प्लगइन को Advanced settings के अंतर्गत अपने खुद के एक्सेस टोकन से सेट किया हो।

अपने खुद के Square एप्लिकेशन का उपयोग करके एक जोड़ने के लिए:

1. सेटिंग्स स्क्रीन पर, Terminal → Webhooks के अंतर्गत, webhook URL कॉपी करने के लिए Copy पर क्लिक करें
2. Square Developer Dashboard में, अपना एप्लिकेशन खोलें और Webhooks पर जाएँ
3. terminal.checkout.updated ईवेंट के लिए एक सब्सक्रिप्शन जोड़ें, और उस URL को notification URL के रूप में चिपकाएँ
4. Square से Webhook Signature Key कॉपी करके प्लगइन की Advanced settings में डालें

इसके बाद Webhooks पंक्ति बताती है कि कोई सिग्नेचर-सत्यापित webhook आया है या नहीं, और कब आया।

URL बिल्कुल मेल खाना चाहिए

Square हर webhook पर उसी notification URL के आधार पर हस्ताक्षर करता है जो उसे दिया गया था। यदि Square में मौजूद URL प्लगइन के URL से एक अक्षर भी भिन्न है, तो हर डिलीवरी सत्यापन में विफल हो जाएगी। इसे टाइप करने के बजाय Copy बटन का उपयोग करें।

यह चरण मैन्युअल क्यों है

Square का Webhook Subscriptions API एप्लिकेशन के दायरे में है, अलग-अलग विक्रेताओं के नहीं, और इसे विक्रेता एक्सेस टोकन से कॉल नहीं किया जा सकता। इसलिए प्लगइन आपके लिए सब्सक्रिप्शन नहीं बना सकता।

यदि webhooks सत्यापित होना बंद कर दें

Webhooks पंक्ति Not verified yet दिखाती है जब वर्तमान सेटिंग्स के अंतर्गत कोई webhook आया और सत्यापित नहीं हुआ है। यदि भुगतान पहले ही चल चुके हैं, तो इस क्रम में जाँचें:

1. Advanced settings में Webhook Signature Key वही है जो Square में है
2. Square में notification URL प्लगइन में दिखाए गए URL से बिल्कुल मेल खाता है
3. terminal.checkout.updated ईवेंट सब्सक्राइब किया गया है
4. आपकी साइट HTTPS पर सार्वजनिक रूप से पहुँच योग्य है — Square Dashboard में डिलीवरी प्रयास जाँचें

environment, webhook URL, या सिग्नेचर कुंजी बदलने पर यह पंक्ति अगला webhook आने तक रीसेट हो जाती है। यह जानबूझकर है: पुरानी सेटिंग्स के अंतर्गत सत्यापित हुई डिलीवरी नई सेटिंग्स के बारे में कुछ नहीं बताती।

सेटिंग्स संदर्भ

सेटिंग्स स्क्रीन उसी क्रम में व्यवस्थित है जिस क्रम में सेटअप चलता है।

अनुभाग	इसमें क्या है
Square account	Environment, Connect to Square, Location ID
Terminal	पेयरिंग नियंत्रण, रीडर सूची, webhook स्थिति
Checkout behaviour	रसीद स्क्रीन छोड़ना, हस्ताक्षर लेना, डिबग लॉग
Advanced settings	एक्सेस टोकन, webhook सिग्नेचर कुंजी, webhook URL ओवरराइड

Advanced settings डिफ़ॉल्ट रूप से बंद रहती है। इसमें मैन्युअल एक्सेस टोकन होते हैं — जिनकी आवश्यकता केवल तब है जब आप कनेक्ट नहीं कर रहे — और webhook सिग्नेचर कुंजी। Webhook URL override खाली ही रहना चाहिए, जब तक आपका सार्वजनिक URL प्लगइन द्वारा निकाले गए URL से भिन्न न हो, उदाहरण के लिए किसी प्रॉक्सी या कस्टम डोमेन के पीछे।

उपयोग

भुगतान प्रोसेस करना

1. आइटम जोड़ें: POS में अपने कार्ट में उत्पाद जोड़ें
2. गेटवे चुनें: भुगतान विधि के रूप में "Square Terminal" चुनें
3. डिवाइस चुनें: Terminal Device सूची से पेयर किया गया टर्मिनल चुनें
4. भुगतान शुरू करें: Start Payment पर क्लिक करें — Square चेकआउट को डिवाइस पर भेजता है
5. ग्राहक भुगतान: ग्राहक Square Terminal पर अपना कार्ड टैप, इंसर्ट या स्वाइप करता है
6. पूर्णता: प्रतीक्षा के दौरान स्थिति लाइव अपडेट होती है, और Square द्वारा भुगतान की पुष्टि होते ही ऑर्डर भुगतान-प्राप्त के रूप में चिह्नित हो जाता है

Sandbox में, डिवाइस सूची में Square के प्रलेखित परीक्षण डिवाइस ID होते हैं, इसलिए हर परिणाम — सफलता, टाइमआउट, ऑफ़लाइन — बिना हार्डवेयर के आज़माया जा सकता है।

भुगतान नियंत्रण

• Start Payment: चयनित टर्मिनल पर नया भुगतान अनुरोध भेजें
• Cancel Payment: टर्मिनल पर इस समय चल रहे भुगतान को रद्द करें
• Check Status: Square से वर्तमान स्थिति तुरंत पूछें
• Release Payment: प्रतिक्रिया न देने वाले टर्मिनल को अलग करें ताकि ऑर्डर का भुगतान किसी अन्य तरीके से किया जा सके; छोड़ा गया चेकआउट फिर भी पृष्ठभूमि में मिलान कर लिया जाता है
• Payment Log: प्रति-ऑर्डर एक वैकल्पिक लॉग जो हर Square चरण और परिणाम रिकॉर्ड करता है

ऑर्डर प्रबंधन

• सत्यापित पूर्णता: ऑर्डर तभी भुगतान-प्राप्त चिह्नित होते हैं जब भुगतान Square के Payment ऑब्जेक्ट के विरुद्ध सत्यापित हो जाए — कभी किसी असत्यापित संकेत पर नहीं
• भुगतान ट्रैकिंग: Square पहचानकर्ता और एक भुगतान लॉग ऑर्डर पर संग्रहीत होते हैं, और मुख्य चरण ऑर्डर नोट्स में लिखे जाते हैं
• रसीद जनरेशन: सफल भुगतानों के बाद मानक POS रसीदें जनरेट होती हैं

आवश्यकताएँ

Square खाता: सक्रिय Square विक्रेता खाता

Square लोकेशन: एक Square location, और उसका Location ID

संगत हार्डवेयर: एक Square Terminal डिवाइस, जो ऑनलाइन हो और उसी Square location में साइन इन हो

सार्वजनिक HTTPS साइट: केवल तभी आवश्यक जब आप webhooks चाहते हैं; उनके बिना भी भुगतान पोलिंग से पुष्ट होते हैं

WCPOS: POS चेकआउट के लिए Pro संस्करण आवश्यक

हार्डवेयर संगतता

कनेक्टिविटी आवश्यकताएँ

Square Terminal, Square के server-side Terminal API का उपयोग करता है: चेकआउट आपकी साइट द्वारा बनाया जाता है और Square द्वारा पेयर किए गए डिवाइस तक पहुँचाया जाता है। टर्मिनल ऑनलाइन होना चाहिए और प्लगइन के समान ही Square खाते और location में साइन इन होना चाहिए।

समर्थित टर्मिनल

• Square Terminal ✅ — Square का समर्पित काउंटरटॉप कार्ड टर्मिनल

दायरा और सीमाएँ

वर्तमान दायरा

• यह POS / order-pay प्रवाहों पर केंद्रित है। ग्राहक-सामने वाले स्टोरफ़्रंट चेकआउट पर उपलब्धता डिफ़ॉल्ट रूप से बंद है और उसे स्पष्ट रूप से सक्षम करना होता है।
• केवल भुगतान लेता है — रिफंड अभी समर्थित नहीं हैं। Square पहचानकर्ता ऑर्डर पर संग्रहीत होते हैं ताकि बाद में रिफंड समर्थन जोड़ा जा सके।
• Webhook सब्सक्रिप्शन Square में मैन्युअल रूप से जोड़ने होते हैं; Webhooks देखें।

समस्या समाधान

सामान्य समस्याएँ

Terminal Device सूची खाली है

• Terminal को पहले इस प्लगइन के साथ पेयर करना आवश्यक है — Create Device Code का उपयोग करें और कोड डिवाइस पर दर्ज करें
• Square Dashboard या Square POS ऐप के माध्यम से पेयर किया गया Terminal तब तक दिखाई नहीं देगा जब तक उसे यहाँ पेयर न किया जाए
• Check for readers पर क्लिक करें: यदि वह Other devices Square can see के अंतर्गत दिखता है, तो वह मौजूद तो है लेकिन इस प्लगइन के साथ पेयर नहीं है
• पुष्टि करें कि Location ID उसी location से मेल खाता है जिसमें Terminal साइन इन है

डिवाइस पेयर नहीं हो रहा

• सुनिश्चित करें कि आपने Device Code उसके समाप्त होने से पहले दर्ज किया — Create Device Code से नया बनाएँ
• पुष्टि करें कि टर्मिनल ऑनलाइन है और प्लगइन के समान ही Square खाते और Location ID में साइन इन है
• जाँचें कि Environment उस खाते से मेल खाता है जिसमें टर्मिनल साइन इन है

Validate Settings विफल हो रहा है

• यदि कनेक्ट है, तो जाँचें कि Square account पंक्ति अब भी Connected to Square दिखाती है; यदि वह आपसे दोबारा कनेक्ट करने को कहती है, तो अधिकरण समाप्त हो चुका है
• यदि आप एक्सेस टोकन उपयोग कर रहे हैं, तो सत्यापित करें कि वह चयनित Environment से मेल खाता है — Sandbox टोकन Production में काम नहीं करेगा, और इसका उल्टा भी सही है
• पुष्टि करें कि Location ID उसी खाते का है

भुगतान टर्मिनल पर पूरा हो जाता है लेकिन ऑर्डर धीरे अपडेट होता है

• webhooks इसी को ठीक करते हैं। उनके बिना, ऑर्डर तब अपडेट होता है जब पोलिंग या पृष्ठभूमि स्वीपर अगली बार उसका मिलान करता है
• Webhooks पंक्ति जाँचें — यदि भुगतान चल चुकने के बाद भी वह Not verified yet कहती है, तो यदि webhooks सत्यापित होना बंद कर दें का पालन करें
• ऑर्डर कभी नहीं खोता: पोल से छूटे किसी भी भुगतान का मिलान स्वीपर कर देता है

भुगतान शुरू नहीं हो रहा

• पुष्टि करें कि कोई टर्मिनल चुना गया है और डिवाइस पेयर तथा ऑनलाइन है
• जाँचें कि डिवाइस कॉन्फ़िगर किए गए Location ID में साइन इन है
• Square API संदेशों के लिए Payment Log और WooCommerce > Status > Logs देखें

यह कहता है कि Square से दोबारा कनेक्ट करना आवश्यक है

Square अधिकरण स्वतः नवीनीकृत होते हैं। यदि कोई नवीनीकरण पूरा नहीं हो पाता, तो प्लगइन उसे अनुपयोगी स्थिति में छोड़ने के बजाय अधिकरण समाप्त कर देता है, और सेटिंग्स स्क्रीन आपसे दोबारा कनेक्ट करने को कहती है। Reconnect to Square पर क्लिक करें — और कुछ बदलने की आवश्यकता नहीं है।

मदद प्राप्त करना

तकनीकी सहायता के लिए:

• समस्याएँ रिपोर्ट करने के लिए GitHub रिपॉज़िटरी देखें
• हार्डवेयर और API मार्गदर्शन के लिए Square Terminal API दस्तावेज़ देखें
• खाता और हार्डवेयर संबंधी समस्याओं के लिए Square सहायता से संपर्क करें

लॉग WooCommerce > Status > Logs में sqtwc हैंडल के अंतर्गत लिखे जाते हैं, और हर डिवाइस लुकअप तथा webhook परिणाम रिकॉर्ड करते हैं।

स्क्रीनशॉट

निम्नलिखित दिखाने के लिए भविष्य के अपडेट में स्क्रीनशॉट जोड़े जाएँगे:

• Square account, Terminal, और Advanced settings अनुभाग
• WCPOS सेटिंग्स में गेटवे सक्षम करना
• POS चेकआउट में भुगतान प्रोसेसिंग वर्कफ़्लो