मुख्य कंटेंट तक स्किप करें

HTML फ़ॉर्म

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

फ़ॉर्म सिर्फ़ POST से https://dash.bitsby.app/invoices/form पर सबमिट होता है और इसमें दो फ़ील्ड होते हैं:

फ़ील्डइसमें क्या है
dataइनवॉइस फ़ील्ड वाले JSON का base64url
signaturedata स्ट्रिंग का HMAC-SHA256, 64 hex अक्षर

एक प्रोजेक्ट में इस तरीके से बने ऐसे इनवॉइस, जिनका भुगतान बाकी है, किसी भी समय ज़्यादा से ज़्यादा 50 हो सकते हैं।

फ़ॉर्म का उदाहरण​

<form method="post" action="https://dash.bitsby.app/invoices/form" target="_blank">
    <input type="hidden" name="data" value="eyJwcm9qZWN0SWQiOiJhMWIyYzNkNC01ZTZm...">
    <input type="hidden" name="signature" value="f77d6da1be35bd2900e0bfed9f202b04...">
    <button type="submit">Pay</button>
</form>

पेज रेंडर करते समय दोनों मान स्टोर का सर्वर भरता है। गुप्त कुंजी कभी मार्कअप में नहीं आती।

target="_blank" एट्रिब्यूट वैकल्पिक है: इसके साथ कार्ट मूल टैब में खुला रहता है।

कंटेनर कैसे बनता है​

  1. इनवॉइस फ़ील्ड के साथ एक JSON ऑब्जेक्ट बनाएँ।
  2. उसे base64url में एनकोड करें। यही data स्ट्रिंग है।
  3. signature = HMAC-SHA256(data, formSecret) की गणना करें।

हस्ताक्षर पूरी data स्ट्रिंग पर एक साथ होता है, इसलिए JSON की कुंजियों का क्रम, इंडेंटेशन और Unicode एस्केपिंग का तरीका मायने नहीं रखता। रिसीवर सामान्य base64 भी स्वीकार करता है, padding के साथ या उसके बिना।

हस्ताक्षर के बाद data दोबारा न बनाएँ: एक भी बाइट बदलने पर हस्ताक्षर फिर से निकालना पड़ता है।

हस्ताक्षर की गणना कैसे करें, चार भाषाओं में तैयार उदाहरणों के साथ, HTML फ़ॉर्म का हस्ताक्षर में बताया गया है।

data के भीतर की कुंजियाँ​

कुंजीअनिवार्यइसमें क्या है
projectIdहाँडैशबोर्ड की सेटिंग्स से प्रोजेक्ट ID, uuid
amountFiatहाँ1 से 1,00,000 तक की राशि, ज़्यादा से ज़्यादा दो दशमलव स्थान। स्ट्रिंग "10.50" या संख्या 10.5 के रूप में
currencyFiatहाँफ़िएट मुद्रा: USD, EUR या RUB
timeToPayहाँभुगतान की समय-सीमा, घंटों में: 0.5, 1, 3, 6, 12। स्ट्रिंग या संख्या के रूप में
descriptionनहींग्राहक के लिए विवरण, ज़्यादा से ज़्यादा 1,000 अक्षर
serviceDataनहींस्टोर की ओर का ऑर्डर ID, ज़्यादा से ज़्यादा 1,000 अक्षर। ग्राहक को नहीं दिखता, लेकिन फ़ॉर्म के सोर्स कोड में दिखता है — यहाँ कोई संवेदनशील चीज़ न रखें
outputनहींerrors — वैलिडेशन की त्रुटियों का ब्यौरा दिखाएँ

वैकल्पिक कुंजी को JSON से हटाया जा सकता है — यह खाली स्ट्रिंग के बराबर है। कुंजियाँ किसी भी क्रम में जा सकती हैं; अनजान कुंजियों को रिसीवर अनदेखा करता है।

मान JSON की स्ट्रिंग या संख्याएँ हैं। Boolean, array और नेस्टेड ऑब्जेक्ट फ़ील्ड के मान नहीं गिने जाते और खाली स्ट्रिंग के रूप में पहुँचते हैं।

data की सामग्री का उदाहरण:

{
    "projectId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "amountFiat": 10.5,
    "currencyFiat": "USD",
    "timeToPay": 1,
    "description": "Order #7, delivery",
    "serviceData": "order-7"
}

यहाँ राशि और भुगतान की समय-सीमा संख्याओं के रूप में भेजी गई हैं; स्ट्रिंग भी स्वीकार होती हैं। वैकल्पिक output बिलकुल सेट नहीं है।

राशि का फ़ॉर्मैट​

सिर्फ़ अंक और दशमलव बिंदु, ज़्यादा से ज़्यादा दो दशमलव स्थान: 10, 10.00, 1000.50। आगे-पीछे के स्पेस हटा दिए जाते हैं।

कोई भी दूसरा फ़ॉर्मैट अस्वीकार हो जाता है — हज़ार के विभाजक, बिंदु की जगह अल्पविराम, exponential notation, संख्या से पहले चिह्न, मुद्रा का प्रतीक। कोई राउंडिंग नहीं होती: तीसरा दशमलव स्थान काटा नहीं जाता, वह अस्वीकृति का कारण बनता है।

फ़ॉर्म की गुप्त कुंजी​

यह गुप्त कुंजी डैशबोर्ड में प्रोजेक्ट सेटिंग्स के फ़ॉर्म की गुप्त कुंजी (Form secret) फ़ील्ड में रहती है। प्रोजेक्ट बनने पर सर्वर इसे जारी करता है। अपना मान सेट नहीं किया जा सकता; गुप्त कुंजी को सिर्फ़ दोबारा जारी किया जा सकता है — जैसे, उसके लीक हो जाने पर।

गुप्त कुंजी स्टोर के सर्वर पर ही रहनी चाहिए। अगर वह स्टोर के HTML में पहुँच जाती है, तो हस्ताक्षर बेमतलब हो जाता है।

फ़ॉर्म की गुप्त कुंजी और Webhook की गुप्त कुंजी अलग-अलग कुंजियाँ हैं; इन्हें आपस में न मिलाएँ।

ऑर्डर ID​

serviceData हमेशा भरें: उसमें अपना ऑर्डर ID रखें। यह मान भुगतान की सूचना में वापस आता है — स्टोर इसी से ऑर्डर खोजता है।

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

हर ऑर्डर के लिए मान अनोखा होना चाहिए। एक जैसे मान पर दूसरा ग्राहक पहले ग्राहक के उस इनवॉइस पर पहुँच जाता है, जिसका भुगतान बाकी है।

खाली serviceData यह सुरक्षा हटा देता है: दोहराव पहचानने का कोई आधार नहीं बचता, और हर सबमिट नया इनवॉइस बनाता है। डुप्लीकेट ऐसे इनवॉइस की 50 वाली सीमा खा जाते हैं, जिनका भुगतान बाकी है, और जब उनमें से किसी का भुगतान हो जाता है, तो स्टोर के पास भुगतान को ऑर्डर से जोड़ने का कोई ज़रिया नहीं होता।

त्रुटियाँ और डीबग मोड​

फ़ॉर्म दो जाँचों से गुज़रता है: पहले हस्ताक्षर और कंटेनर, फिर फ़ील्ड के मान।

क्या हुआसेवा क्या दिखाती है
हस्ताक्षर मेल नहीं खाता, कंटेनर पढ़ा नहीं जा सकता, प्रोजेक्ट किसी और का है या मौजूद नहीं हैसामान्य त्रुटि, कारण नहीं बताया जाता
हस्ताक्षर मेल खाता है, लेकिन कोई फ़ील्ड ग़लत भरा हैसामान्य त्रुटि। "output":"errors" के साथ — त्रुटियों का ब्यौरा
दोनों जाँचें पास हुईंइनवॉइस वाला भुगतान पृष्ठ

पहली जाँच किसी भी सेटिंग में कारण नहीं खोलती।

JSON में "output":"errors" जोड़ी दूसरी जाँच का ब्यौरा चालू करती है: सेवा फ़ील्ड का नाम बताती है, मान्य मान गिनाती है और यह भी बताती है कि भुगतान बाकी वाले इनवॉइस की 50 की सीमा पूरी हो चुकी है। यह कुंजी साइन किए हुए कंटेनर के भीतर रहती है, इसलिए इसे बाहर से घुसाया नहीं जा सकता।

फ़ॉर्म सेट करते समय JSON में "output":"errors" रखें; सेटअप पूरा होने पर कुंजी हटाएँ और कंटेनर दोबारा बनाएँ।

अगर हस्ताक्षर ही मेल नहीं खाता, तो अपने data और हस्ताक्षर की तुलना HTML फ़ॉर्म का हस्ताक्षर में दिए संदर्भ सेट से करें।

आगे क्या​

फ़ॉर्म से बना इनवॉइस उसी तरह प्रोसेस होता है, जैसे API या डैशबोर्ड से बना:

आखरी अपडेट पर