Webhook URL

جائزہ

یہ فیچر ادا شدہ انوائس کا ڈیٹا تاجر کے سرور تک پہنچاتا ہے۔ اس کا مقصد یہ ہے کہ تاجر کا اسٹور ادائیگی کو خودکار طور پر پروسیس کرے اور آپ کے گاہک کو پروڈکٹ یا سروس پہنچائے۔

Webhook URL ہر پروجیکٹ کے لیے الگ سے سیٹ ہوتا ہے اور تاجر کے اسٹور کے اندر ادائیگی کے ہینڈلر اسکرپٹس کی طرف اشارہ کرتا ہے۔ ایڈریس میں HTTPS اور ڈومین نام ہونا ضروری ہے: سروس IP ایڈریس قبول نہیں کرتی، اور ہر ڈیلیوری پر سرٹیفکیٹ جانچتی ہے۔

جب بھی کسی انوائس کا اسٹیٹس ادا شدہ (Paid) ہو جاتا ہے، سروس اس URL پر درج ذیل فارمیٹ میں POST درخواست بھیجتی ہے:

{
   "wallet":{
      "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
      "name":"usdt-tron",
      "blockchain":"tron",
      "cryptocurrency":"usdt",
      "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
   },
   "project":{
      "id":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
      "name":"My project",
      "commissionPayer":"seller",
      "commissionRate":1
   },
   "invoice":{
      "id":"a4c9e2ee-9a03-43e5-a1a1-00caf679d16a",
      "uid":"AFhygKX21ecd",
      "createDatetime":"2024-02-26 13:29:24",
      "timeToPayDatetime":"2024-02-27 01:29:24",
      "commissionFiatUSD":0.05,
      "amountFiatUSD":5.02,
      "amountFiat":5,
      "calcAmountFiat":5.02,
      "currencyFiat":"USD",
      "description":null,
      "serviceData":null,
      "status":"paid"
   },
   "payment":{
      "id":"f986ad8d-2298-473d-982a-efbc817b975d",
      "amount":5.02,
      "hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
      "transactionDatetime":"2024-02-26 13:32:57"
   }
}

اطلاع ادا شدہ اسٹیٹس میں ہر منتقلی پر جاتی ہے — جب سروس نے ادائیگی خودکار طور پر تلاش کی ہو اور جب تاجر نے ادائیگی کو دستی طور پر انوائس سے منسلک کیا ہو، دونوں صورتوں میں۔

درخواست کے پیرامیٹرز

پیرامیٹر	تفصیل
wallet.id	UUID فارمیٹ میں والٹ ID
wallet.name	والٹ کا نام
wallet.blockchain	کرپٹو والٹ کا بلاک چین
wallet.cryptocurrency	والٹ کی کرپٹو کرنسی
wallet.address	کرپٹو والٹ کا ایڈریس
project.id	UUID فارمیٹ میں پروجیکٹ ID
project.name	پروجیکٹ کا نام
project.commissionPayer	سروس فیس کون ادا کرتا ہے
project.commissionRate	فیس کی شرح، % میں
invoice.id	UUID فارمیٹ میں انوائس ID
invoice.uid	انوائس ID (گاہک کے لیے)
invoice.createDatetime	انوائس بننے کی تاریخ اور وقت (UTC)
invoice.timeToPayDatetime	وہ تاریخ اور وقت جب تک انوائس گاہک کے لیے درست رہتی ہے (UTC)۔ ادائیگی کی تلاش اس وقت کے بعد مزید ایک گھنٹے تک جاری رہتی ہے — سست نیٹ ورکس کی وجہ سے۔ اس لیے ایسی انوائس کی اطلاع بھی آ سکتی ہے جو گاہک کو پہلے ہی میعاد ختم دکھائی گئی تھی
invoice.commissionFiatUSD	سروس فیس کی رقم۔ اس کا حساب invoice.amountFiatUSD کی رقم سے ہوتا ہے
invoice.amountFiatUSD	USD میں رقم۔ انوائس بنتے وقت اس کا حساب invoice.amountFiat سے موجودہ شرح تبادلہ پر ہوتا ہے۔ ادائیگی کے لمحے سروس اسے اصل میں موصول ہونے والی رقم سے بدل دیتی ہے، جو اس لمحے کی شرح تبادلہ پر USD میں تبدیل ہوتی ہے۔ invoice.commissionFiatUSD میں فیس بھی اسی سے دوبارہ شمار ہوتی ہے
invoice.amountFiat	فیاٹ کرنسی میں انوائس کی اصل رقم۔ نہیں بدلتی
invoice.calcAmountFiat	ادائیگی کے لمحے کی کرپٹو شرح تبادلہ پر invoice.currencyFiat کرنسی میں شمار شدہ رقم۔ یہ invoice.amountFiat سے مختلف ہو سکتی ہے، کیونکہ ممکن ہے گاہک نے انوائس فوراً نہیں بلکہ بننے کے کچھ دیر بعد ادا کی ہو۔ اس دوران invoice.currencyFiat کے مقابلے میں کرپٹو کی شرح تبادلہ کسی بھی سمت میں بدل سکتی تھی
invoice.currencyFiat	فیاٹ کرنسی
invoice.description	انوائس بناتے وقت دی گئی تفصیل
invoice.serviceData	انوائس بناتے وقت دیا گیا سروس ڈیٹا
invoice.status	انوائس کا اسٹیٹس
payment.id	UUID فارمیٹ میں ادائیگی کی ID
payment.amount	کرپٹو کرنسی میں ادائیگی کی رقم
payment.hash	آن چین ٹرانزیکشن کا ہیش
payment.transactionDatetime	آن چین ٹرانزیکشن کی تاریخ اور وقت (UTC)

اطلاع کا دستخط

ہر درخواست پر Webhook کی خفیہ کلید سے دستخط ہوتا ہے۔ دستخط X-Timestamp اور X-Signature ہیڈرز میں جاتا ہے اور آپ کو یہ یقینی بنانے دیتا ہے کہ اطلاع سروس کی طرف سے آئی ہے، کسی ایسے باہر کے شخص کی طرف سے نہیں جسے آپ کے ہینڈلر کا ایڈریس معلوم ہو گیا ہو۔

آرڈر پروسیس کرنے سے پہلے دستخط جانچیں۔ طریقہ کار اور تیار مثالیں Webhook کے دستخط کی جانچ میں ہیں۔

ہینڈلنگ کی سفارشات

ادائیگی کی مہلت گزر جانے کی وجہ سے اطلاع کو رد نہ کریں۔ «انوائس کی میعاد ختم ہو چکی ہے، اس لیے ادائیگی غلط ہے» جیسی جانچ منطقی لگتی ہے لیکن حقیقی ادائیگیوں کا ایک حصہ کاٹ دیتی ہے: سست نیٹ ورکس پر ٹرانزیکشن کی تصدیق مہلت کے بعد ہو سکتی ہے، اور تاجر دستی طور پر ادائیگی کو میعاد ختم انوائس سے منسلک کر سکتا ہے۔ اطلاع بذات خود ادائیگی کی تصدیق کرتی ہے۔

رقم کو اصل فیلڈ سے ملا کر جانچیں، یعنی invoice.amountFiat سے۔ یہ جاری کی گئی انوائس کی رقم ہے، اور یہ نہیں بدلتی۔ amountFiatUSD فیلڈ اصل میں موصول ہونے والی رقم دکھاتی ہے اور جاری کردہ رقم سے مختلف ہو سکتی ہے — شرح تبادلہ میں اتار چڑھاؤ کی وجہ سے بھی اور ادائیگی کو دستی طور پر منسلک کرنے کی وجہ سے بھی۔

رقموں کو نمبرز کے طور پر پارس کریں۔ آخر کے صفر ختم ہو جاتے ہیں: 10.00 کی رقم 10 کے طور پر آتی ہے؛ ڈسپلے کے لیے اسے اپنی طرف فارمیٹ کریں۔ 0.0001 سے کم رقمیں exponential نوٹیشن میں آتی ہیں، مثال کے طور پر 1.0e-6 — معیاری JSON پارسنگ درست نمبر دیتی ہے؛ صرف اسٹرنگ کی دستی پارسنگ ٹوٹتی ہے۔

اطلاعات کو idempotent طریقے سے ہینڈل کریں۔ ایک ہی اطلاع دوبارہ آ سکتی ہے — مثال کے طور پر، اگر آپ کے اسکرپٹ نے ادائیگی کامیابی سے پروسیس کر لی لیکن 2xx کے علاوہ کوئی کوڈ واپس کیا۔ آرڈر مکمل کرنے سے پہلے جانچیں کہ آیا یہ invoice.id پہلے ہی پروسیس ہو چکی ہے۔

آؤٹ پٹ پر قدروں کو escape کریں۔ invoice.description اور invoice.serviceData فیلڈز بالکل اسی طرح واپس آتی ہیں جیسے تاجر نے انہیں بھیجا تھا۔ اگر آپ انہیں HTML میں دکھاتے ہیں، تو انہیں اپنی طرف escape کریں۔

ڈیلیوری کا شیڈول

Webhook URL والے سرور کو 2xx HTTP کوڈ کے ساتھ جواب دینا ضروری ہے۔ کوئی اور کوڈ، ٹائم آؤٹ یا کنکشن کا ٹوٹ جانا ناکام ڈیلیوری شمار ہوتا ہے۔

سروس ری ڈائریکٹس کو فالو نہیں کرتی: 301 یا 302 جواب ناکام ڈیلیوری ہے، نئے ایڈریس پر منتقلی نہیں۔ ہینڈلر کا حتمی ایڈریس سیٹ کریں۔

کنکشن کے لیے 5 سیکنڈ اور پوری درخواست کے لیے 10 سیکنڈ کی اجازت ہے۔ اگر ہینڈلر اس وقت میں مکمل نہ ہو، تو ڈیلیوری ناکام شمار ہوتی ہے۔

ناکام ڈیلیوری کے بعد سروس درج ذیل شیڈول پر دوبارہ کوشش کرتی ہے:

• آخری ناکام ڈیلیوری کے 5 منٹ بعد
• 15 منٹ بعد
• 30 منٹ بعد
• ایک گھنٹے بعد
• 3 گھنٹے بعد
• 6 گھنٹے بعد
• 12 گھنٹے بعد
• 24 گھنٹے بعد

اس کے بعد ڈیلیوری کی کوششیں رک جاتی ہیں۔

Webhook URL کو غیر فعال کرنا

کبھی کبھار اسٹور کا Webhook اسکرپٹ ادائیگی کو درست طور پر پروسیس کرتا ہے لیکن 2xx کے علاوہ کوئی HTTP کوڈ واپس کرتا ہے۔ اس سے اوپر دیے گئے شیڈول کے مطابق ہمارے سرور سے بار بار دوبارہ کوششیں ہوتی ہیں، جو ہمارے اور آپ کے دونوں سرورز پر اضافی بوجھ ڈالتی ہیں۔

ایسے معاملات روکنے کے لیے ہمارے پاس ایک طریقہ کار ہے جو پروجیکٹ میں Webhook URL کو غیر فعال کر دیتا ہے۔ اس سے بچنے کے لیے یہ اقدامات کریں:

1. اپنے Webhook ہینڈلر کا کوڈ بدلیں تاکہ وہ ادائیگی کی کامیاب پروسیسنگ پر 2xx کوڈ، عام طور پر 200، واپس کرے۔ اسے کسی بھی ایمولیٹر سے ٹیسٹ کریں، مثال کے طور پر Postman۔
2. سیٹنگز درست کروانے کے لیے تکنیکی معاونت سے رابطہ کریں۔
3. پروجیکٹ کی سیٹنگز میں Webhook URL دوبارہ فعال کریں اور پروجیکٹ محفوظ کریں۔