HTML فارمز

ویب سائٹ، آن لائن اسٹور یا بوٹ میں کرپٹو ادائیگیاں شامل کرنے کا ایک طریقہ۔ گاہک بٹن پر کلک کرتا ہے، اور انوائس کے ساتھ ادائیگی کا صفحہ کھل جاتا ہے۔

فارم صرف POST کے ذریعے https://dash.bitsby.app/invoices/form پر جاتا ہے اور اس میں دو فیلڈز ہوتی ہیں:

فیلڈ	اس میں کیا ہوتا ہے
data	انوائس کی فیلڈز والے JSON کا base64url
signature	data اسٹرنگ کا 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 escaping کا طریقہ کوئی فرق نہیں ڈالتا۔ وصول کنندہ معیاری base64 بھی قبول کرتا ہے، پیڈنگ کے ساتھ یا اس کے بغیر۔

دستخط کے بعد data کو دوبارہ نہ بنائیں: اگر ایک بائٹ بھی بدل جائے تو دستخط کا حساب دوبارہ لگانا ہوگا۔

دستخط کا حساب کیسے لگائیں، اور چار زبانوں میں تیار مثالیں، اس کی تفصیل HTML فارم کا دستخط میں ہے۔

data کے اندر کلیدیں

کلید	لازمی	اس میں کیا ہوتا ہے
projectId	ہاں	ڈیش بورڈ کی سیٹنگز سے پروجیکٹ ID، uuid
amountFiat	ہاں	1 سے 100,000 تک رقم، اعشاریہ کے بعد زیادہ سے زیادہ دو ہندسے۔ اسٹرنگ "10.50" یا نمبر 10.5 کی صورت میں
currencyFiat	ہاں	فیاٹ کرنسی: USD، EUR یا RUB
timeToPay	ہاں	ادائیگی کی مہلت گھنٹوں میں: 0.5، 1، 3، 6، 12۔ اسٹرنگ یا نمبر کی صورت میں
description	نہیں	گاہک کے لیے تفصیل، 1,000 حروف تک
serviceData	نہیں	اسٹور کی طرف آرڈر کی شناخت، 1,000 حروف تک۔ گاہک کو نظر نہیں آتی لیکن فارم کے سورس کوڈ میں دکھائی دیتی ہے — یہاں کوئی حساس چیز نہ رکھیں
output	نہیں	errors — ویلیڈیشن کی غلطیوں کی تفصیل دکھائیں

آپ اختیاری کلید کو JSON سے چھوڑ سکتے ہیں — یہ خالی اسٹرنگ کے برابر ہے۔ کلیدیں کسی بھی ترتیب میں ہو سکتی ہیں؛ وصول کنندہ نامعلوم کلیدوں کو نظر انداز کرتا ہے۔

قدریں JSON اسٹرنگز یا نمبرز ہوتی ہیں۔ boolean، array اور nested object قسم کی قدریں فیلڈ کی قدر شمار نہیں ہوتیں اور خالی اسٹرنگ کے طور پر پہنچتی ہیں۔

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 نوٹیشن، نمبر سے پہلے کوئی علامت، کرنسی کا نشان۔ راؤنڈنگ نہیں ہوتی: اعشاریہ کے بعد تیسرا ہندسہ کاٹا نہیں جاتا، بلکہ اس کی وجہ سے فارم رد ہو جاتا ہے۔

فارم کی خفیہ کلید

خفیہ کلید ڈیش بورڈ میں پروجیکٹ کی سیٹنگز میں، فارم کی خفیہ کلید (Form secret) فیلڈ میں ہوتی ہے۔ سرور اسے پروجیکٹ بنتے وقت جاری کرتا ہے۔ آپ اپنی قدر سیٹ نہیں کر سکتے؛ خفیہ کلید صرف دوبارہ جاری کروائی جا سکتی ہے — مثال کے طور پر، اگر وہ افشا ہو جائے۔

خفیہ کلید اسٹور کے سرور پر ہی رہنی چاہیے۔ اگر یہ اسٹور فرنٹ کے HTML میں پہنچ جائے، تو دستخط بے معنی ہو جاتا ہے۔

فارم کی خفیہ کلید اور Webhook کی خفیہ کلید دو الگ کلیدیں ہیں؛ انہیں آپس میں نہ ملائیں۔

آرڈر کی شناخت

serviceData ہمیشہ بھریں: اس میں اپنے آرڈر کی شناخت رکھیں۔ یہ قدر ادائیگی کی اطلاع میں واپس آتی ہے — اسٹور اسی سے آرڈر تلاش کرتا ہے۔

بھرا ہوا serviceData ڈپلیکیٹس سے بچاتا ہے۔ فارم دوبارہ بھیجنے یا بٹن پر دو بار کلک کرنے سے دوسری انوائس نہیں بنتی: سروس گاہک کو موجودہ غیر ادا شدہ انوائس پر بھیج دیتی ہے۔ موازنہ آرڈر کی فیلڈز پر ہوتا ہے — پروجیکٹ، رقم، کرنسی، تفصیل اور serviceData — نہ کہ data کے بائٹس پر۔

یہ قدر ہر آرڈر کے لیے منفرد ہونی چاہیے۔ ایک ہی قدر کے ساتھ دوسرا گاہک پہلے گاہک کی غیر ادا شدہ انوائس پر پہنچ جاتا ہے۔

خالی serviceData یہ تحفظ ختم کر دیتا ہے: دہرائی گئی درخواست کو پہچاننے کے لیے کچھ نہیں ہوتا، اور ہر سبمٹ ایک نئی انوائس بناتا ہے۔ ڈپلیکیٹس 50 غیر ادا شدہ انوائسز کی حد استعمال کر لیتے ہیں، اور جب ان میں سے کوئی ادا ہو جاتی ہے، تو اسٹور کے پاس ادائیگی کو آرڈر سے جوڑنے کے لیے کچھ نہیں ہوتا۔

غلطیاں اور ڈیبگ موڈ

فارم دو جانچوں سے گزرتا ہے: پہلے دستخط اور کنٹینر، پھر فیلڈز کی قدریں۔

کیا ہوا	سروس کیا دکھاتی ہے
دستخط مماثل نہیں، کنٹینر پڑھا نہیں جا سکتا، پروجیکٹ کسی اور کا ہے یا موجود نہیں	عمومی غلطی، کوئی وجہ بتائے بغیر
دستخط مماثل ہے، لیکن کوئی فیلڈ غلط بھری گئی ہے	عمومی غلطی۔ "output":"errors" کے ساتھ — تفصیلی غلطیاں
دونوں جانچیں کامیاب	انوائس کے ساتھ ادائیگی کا صفحہ

پہلی جانچ کسی بھی سیٹنگ میں وجہ ظاہر نہیں کرتی۔

JSON میں "output":"errors" والا جوڑا دوسری جانچ کی تفصیل آن کرتا ہے: سروس فیلڈ کا نام بتاتی ہے، اجازت شدہ قدروں کی فہرست دیتی ہے، اور بتاتی ہے کہ 50 غیر ادا شدہ انوائسز کی حد پوری ہو گئی ہے۔ یہ کلید دستخط شدہ کنٹینر کے اندر ہوتی ہے، اس لیے کوئی اسے باہر سے شامل نہیں کر سکتا۔

فارم سیٹ اپ کرتے وقت JSON میں "output":"errors" رکھیں؛ سیٹ اپ مکمل ہونے کے بعد کلید ہٹا دیں اور کنٹینر دوبارہ بنائیں۔

اگر خود دستخط مماثل نہیں ہے، تو اپنے data اور دستخط کا موازنہ HTML فارم کا دستخط میں دیے گئے حوالہ جاتی سیٹ سے کریں۔

آگے کیا ہے

سروس فارم سے بننے والی انوائس کو بالکل اسی طرح پروسیس کرتی ہے جیسے API یا ڈیش بورڈ سے بنی انوائس کو:

• ادائیگی کی تصدیق Webhook URL پر آتی ہے۔ Webhook کی خفیہ کلید سے اطلاع کا دستخط جانچیں اور آرڈرز صرف اسی کی بنیاد پر مکمل کریں۔
• گاہک کو آپ کی سائٹ پر واپس بھیجنا کامیابی کے URL (Successful URL) اور ناکامی کے URL (Unsuccessful URL) سے سیٹ ہوتا ہے — انوائس کا لائف سائیکل صفحے پر «گاہک کو اسٹور کی سائٹ پر واپس بھیجنا» سیکشن دیکھیں۔ ان URLs پر پہنچنا ادائیگی کی تصدیق نہیں ہے۔
• انوائس کے اسٹیٹس اور ادائیگی کی تلاش کی مدت کی تفصیل انوائس کا لائف سائیکل میں ہے۔
• گاہک نے غلط رقم منتقل کی — ادائیگیوں کو منسلک کرنا اور رقم کا فرق دیکھیں۔