وثائق المطورين

التحقق من توقيع إشعار الدفع

تحقق من توقيع 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 حرفًا سداسيًا عشريًا صغيرًا. أرسله في X-Bolt-Signature لطلبات API. تحقق من الإشعارات باستخدام 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