डेवलपर दस्तावेज़

भुगतान सूचना का हस्ताक्षर जाँचें

टाइमस्टैम्प और Webhook के मूल अनुरोध पर HMAC-SHA256 से हस्ताक्षर जाँचें। समय, ऑर्डर और दोहराव सत्यापित करके इवेंट सहेजें, फिर HTTP 2xx उत्तर दें।

ये ऑर्डर एपीआई (बनाएं, क्वेरी करें और पुनः भेजें) HMAC-SHA256 हस्ताक्षर का उपयोग करते हैं। GET /api/v1/ping को केवल API कुंजी की आवश्यकता है। भुगतान कॉलबैक में एक हस्ताक्षर भी शामिल है। HMAC आपके व्यापारी Webhook रहस्य का उपयोग करता है, आपकी API कुंजी का नहीं।

01. हेडर विशिष्टताएँ

01. ऑर्डर API अनुरोध भेजा जा रहा है

Client to Server

अनुरोध बनाने, क्वेरी करने और पुनः भेजने के लिए भी X-Bolt-Key की आवश्यकता होती है। timestamp सर्वर क्लॉक के 5 मिनट के भीतर होना चाहिए। पुनः प्रयास करते समय एक नया timestamp और हस्ताक्षर उत्पन्न करें।

Unix मिलीसेकंड timestampआवश्यक
X-Bolt-Timestamp
HMAC-SHA256 हेक्साडेसिमल हस्ताक्षरआवश्यक
X-Bolt-Signature

02. भुगतान कॉलबैक प्राप्त हो रहा है

Server to Merchant

BoltUtil कॉलबैक टाइमस्टैम्प और हस्ताक्षर उत्पन्न करता है। रिसीवर्स को रॉ बॉडी को सत्यापित करना चाहिए, timestamp विंडो की जांच करनी चाहिए और घटनाओं और व्यावसायिक ऑर्डरों को निष्क्रियता से संभालना चाहिए।

Unix मिलीसेकंड timestampआवश्यक
X-Bolt-Webhook-Timestamp
HMAC-SHA256 हेक्साडेसिमल हस्ताक्षरआवश्यक
X-Bolt-Webhook-Signature

02. हस्ताक्षर गणना

1

हस्ताक्षरित सामग्री का निर्माण करें

हेडर का टाइमस्टैम्प, एक बिंदु और अनुरोध का सटीक मूल बॉडी जोड़ें: timestamp + "." + raw_body। UTF-8 प्रयोग करें; बॉडी खाली होने पर भी बिंदु रखें।

// 1. Construct payload: timestamp + "." + body
String payload = timestamp + "." + body;
2

HMAC-SHA256 की गणना करें

अपने व्यापारी Webhook कॉन्फ़िगरेशन से प्राप्त रहस्य का उपयोग करें। हस्ताक्षर करने के लिए उपयोग किया जाने वाला मुख्य भाग आपके API अनुरोध में भेजे गए मुख्य भाग से बिल्कुल मेल खाना चाहिए।

// JDK standard library: javax.crypto.Mac and SecretKeySpec
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
3

लोअरकेस हेक्साडेसिमल के रूप में एन्कोड करें

32 बाइट के डाइजेस्ट को 64 छोटे अक्षरों वाले हेक्साडेसिमल वर्णों में बदलें। API अनुरोध में इसे X-Bolt-Signature में भेजें। सूचना को X-Bolt-Webhook-Signature से स्थिर समय तुलना द्वारा सत्यापित करें।

// JDK 17+: java.util.HexFormat
String signature = HexFormat.of().formatHex(hash);

03. सत्यापन नोट्स

  • सत्यापन से पहले JSON को पार्स और पुनः क्रमांकित न करें। व्हाइटस्पेस, लाइन ब्रेक, कुंजी क्रम और एन्कोडिंग सभी हस्ताक्षर को प्रभावित करते हैं।
  • HMAC सामग्री की अखंडता की पुष्टि करता है, लेकिन स्वयं पुनः प्रसारण को नहीं रोकता है। timestamp ताजगी की जांच करें और ईवेंट को डीडुप्लिकेट करें।
  • एक वैध हस्ताक्षर का मतलब यह नहीं है कि पूर्ति पूरी हो गई है। ऑर्डर एसोसिएशन, भुगतान स्थिति, राशि, मुद्रा और निपटान प्रकार की जांच करें।
कॉलबैक हैंडलिंग देखें →
signature / cURL
# Calculate a request signature without sending a request.
# BOLTUTIL_WEBHOOK_SECRET is your merchant Webhook secret, not API Key.
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')
printf 'X-Bolt-Timestamp: %s\nX-Bolt-Signature: %s\n' "$timestamp" "$signature"
# Send this SAME body with the above headers and X-Bolt-Key.
# Callback header names are X-Bolt-Webhook-Timestamp and
# X-Bolt-Webhook-Signature. Verify raw bytes before parsing JSON.

पते, लेनदेन हैश और ऑर्डर इसके उदाहरण हैं। उन्हें अपने स्वयं के परीक्षण data से बदलें।

Base URL

PROD
https://api.boltutil.com