Webhook

Webhook आपके सिस्टम को PayerScan से स्वचालित रीयल-टाइम सूचनाएं प्राप्त करने की अनुमति देता है। सिस्टम इनवॉइस बनाते समय Merchant द्वारा प्रदान किए गए callback_url पर POST अनुरोध भेजता है।

इवेंट के प्रकार

PayerScan में status फ़ील्ड में 2 मुख्य इवेंट लौटाए जाते हैं:

1. completed — भुगतान सफल: इनवॉइस से मेल खाने वाले लेनदेन की पुष्टि हो गई है (blockchain या Binance Pay)।
2. expired — इनवॉइस समाप्त: इनवॉइस ने भुगतान प्रतीक्षा समय पार कर लिया है।

Merchant को एक सार्वजनिक URL (HTTPS अनुशंसित) प्रदान करना होगा, POST अनुरोध प्राप्त करने होंगे, payload को प्रोसेस करना होगा और निर्दिष्ट timeout (जैसे 10 सेकंड) के भीतर HTTP 2xx लौटाना होगा।

---

Payload संरचना

1. सफल भुगतान पर Webhook (status: completed)

जब मेल खाने वाला लेनदेन मिलता है (सही पता, सही राशि, समय विंडो के भीतर), सिस्टम इनवॉइस को completed में अपडेट करता है और callback_url पर इस payload के साथ POST भेजता है:

Payload (JSON body)

{
  "merchant_id": "MERCHANT_001",
  "api_key": "YOUR_API_KEY",
  "request_id": "order-1234",
  "trans_id": "TID-ABC123DEF4567890",
  "status": "completed",
  "amount": "100",
  "token_symbol": "USDT",
  "token_price": "1",
  "token_amount": "100.0026",
  "network_symbol": "BSC",
  "from_address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
  "to_address": "0xc221460115e2CfCa5bF089A7e647b11cb9631efE",
  "transaction_hash": "0xd346b32b83b35376d42a2464598fbf565fffb39e6569200f034a5e8342c532d7"
}

फ़ील्ड	विवरण
merchant_id	स्टोर का मर्चेंट कोड।
api_key	API Key (यदि आवश्यक हो तो क्रॉस-रेफरेंस के लिए)।
request_id	आपका ऑर्डर ID (अपने आंतरिक इनवॉइस से तुलना के लिए)।
trans_id	इनवॉइस कोड। संबंधित ऑर्डर अपडेट करने के लिए उपयोग करें।
status	हमेशा "completed"।
amount	USD राशि (स्ट्रिंग)।
token_symbol	कॉइन/टोकन (जैसे USDT)।
token_price	लेनदेन के समय विनिमय दर (स्ट्रिंग)। अनुपलब्ध होने पर amount पर fallback हो सकता है।
token_amount	वास्तव में ट्रांसफर की गई क्रिप्टो राशि (स्ट्रिंग)। दुर्लभ मामलों में null हो सकता है।
network_symbol	नेटवर्क (जैसे BSC, TRC20, ETH, SOL, BINANCE_ID, OKX_UID, BYBIT_UID, ...)।
from_address	भेजने वाले का वॉलेट पता।
to_address	प्राप्त करने वाले का वॉलेट पता (स्टोर का)।
transaction_hash	blockchain पर लेनदेन हैश।

Merchant आवश्यकताएं

1. POST प्राप्त करें callback_url से संबंधित endpoint पर।
2. JSON पार्स करें body।
3. सत्यापन (वैकल्पिक लेकिन अनुशंसित): merchant_id या trans_id को अपने आंतरिक डेटा से मिलाएं।
4. ऑर्डर अपडेट करें: trans_id या request_id से मेल खाने वाले ऑर्डर को भुगतान किया गया चिह्नित करें; यदि आवश्यक हो तो transaction_hash सहेजें।
5. HTTP 2xx लौटाएं (जैसे 200 OK) timeout के भीतर (जैसे 10 सेकंड)। Response body की आवश्यकता नहीं है; सिस्टम को webhook सफल मानने के लिए केवल 2xx स्थिति कोड चाहिए।

यदि आप 4xx/5xx या timeout लौटाते हैं, तो सिस्टम callback को failed चिह्नित करता है और पुनः प्रयास तंत्र सक्रिय करता है (पुनः प्रयास की संख्या और अंतराल backend कॉन्फ़िगरेशन पर निर्भर करते हैं)।

---

2. इनवॉइस समाप्ति पर Webhook (status: expired)

जब इनवॉइस expired स्थिति में बदलता है (expires_at पार करने पर), सिस्टम callback_url पर एक सरल payload के साथ POST भेजता है:

Payload (JSON body)

{
  "merchant_id": "MERCHANT_001",
  "request_id": "order-1234",
  "trans_id": "TID-ABC123DEF4567890",
  "status": "expired",
  "amount": "100"
}

फ़ील्ड	विवरण
merchant_id	स्टोर का मर्चेंट कोड।
request_id	आपका ऑर्डर ID (यदि इनवॉइस बनाते समय प्रदान किया गया हो)।
trans_id	इनवॉइस कोड। संबंधित ऑर्डर अपडेट करने के लिए उपयोग करें।
status	हमेशा "expired"।
amount	USD राशि (स्ट्रिंग)।

आप इस जानकारी का उपयोग ऑर्डर को "समाप्त" के रूप में अपडेट करने, आरक्षण रद्द करने आदि के लिए कर सकते हैं। आपको फिर भी HTTP 2xx लौटाना चाहिए ताकि सिस्टम इसे त्रुटि न माने।

---

3. Webhook हैंडलर उदाहरण (Node.js)

app.post('/webhook/payment', express.json(), async (req, res) => {
  const { merchant_id, api_key, trans_id, request_id, status, amount, transaction_hash } = req.body;

  // merchant_id सत्यापित करें (completed और expired दोनों)
  if (merchant_id !== process.env.PAYERSCAN_MERCHANT_ID) {
    return res.status(401).send('Unauthorized');
  }

  // api_key सत्यापित करें (केवल completed — expired में api_key नहीं होती)
  if (status === 'completed' && api_key !== process.env.PAYERSCAN_API_KEY) {
    return res.status(401).send('Unauthorized');
  }

  // request_id या trans_id से ऑर्डर खोजें
  const order = await orderService.findByRequestId(request_id) || await orderService.findByTransId(trans_id);
  if (!order) {
    return res.status(404).send('Order not found');
  }

  if (status === 'completed') {
    await orderService.markPaid(order, { transaction_hash, amount });
  } else if (status === 'expired') {
    await orderService.markExpired(order);
  }

  res.status(200).send('OK');
});

---

हस्ताक्षर सत्यापन

यह सुनिश्चित करने के लिए कि webhook वास्तव में PayerScan से आ रहे हैं, आपको हस्ताक्षर सत्यापित करना चाहिए या डेटा की क्रॉस-रेफरेंस करनी चाहिए।

• HTTPS: सुनगाई को रोकने के लिए callback_url के लिए हमेशा HTTPS का उपयोग करें।
• API Key सत्यापन (केवल completed): completed webhook में payload में आपकी api_key शामिल होती है। प्रामाणिकता सत्यापित करने के लिए इसकी तुलना अपनी संग्रहीत API key से करें। ध्यान दें: expired webhook में api_key शामिल नहीं होती।

---

Idempotency (दोहरे लेनदेन रोकथाम)

एक trans_id को केवल एक completed इवेंट प्राप्त होगा, लेकिन पुनः प्रयास इसे फिर से भेज सकते हैं। सुनिश्चित करें कि आपकी प्रोसेसिंग लॉजिक idempotent है (कई बार अपडेट करना सुरक्षित है, दोहरा क्रेडिट नहीं होगा)।

Webhook विफलता पर पुनः प्रयास

जब Merchant सर्वर त्रुटि (4xx/5xx) लौटाता है या timeout होता है, तो सिस्टम इस अनुसूची के अनुसार webhook पुनः प्रयास करता है:

प्रयास	समय
प्रयास 1	तुरंत (इनवॉइस पूर्ण होने पर)
प्रयास 2	10 सेकंड बाद
प्रयास 3	30 सेकंड बाद
प्रयास 4	30 सेकंड बाद
प्रयास 5	60 सेकंड बाद

अधिकतम 5 प्रयास। 5 विफलताओं के बाद, callback_status failed हो जाता है और कोई और प्रयास नहीं किया जाता।

Merchant को सुनिश्चित करना चाहिए कि उनका endpoint स्थिर है और 2xx तेजी से लौटाता है (< 10 सेकंड) ताकि अनावश्यक पुनः प्रयास से बचा जा सके।