مستندات مكتبة JS SDK

لوحة المحاكاة التفاعلية

بيئة تجربة الـ SDK الحية (Live Playground)

عدل الخيارات لرؤية التغييرات المباشرة وتجربة نافذة الدفع مباشرة دون الحاجة للاتصال الفعلي بالخادم.

مبلغ الدفع (Amount)

نص الزر (Button Text)

تفعيل الموقع (Location) أرقام عربية (١، ٢، ٣) حظر أدوات المطورين (F12) منع الإغلاق العشوائي للمودال (Sticky Modal)

منطقة العرض الحية

كود التضمين المقابل (Code):

index.html

pay.js

آليات حماية الأسعار وتجاوز جدار الحماية (Price Verification)

عند تشغيل واجهة الدفع، يمكن للمخترقين محاولة تعديل قيمة معامل السعر المرسل في الواجهة الأمامية باستخدام أدوات المطورين (DevTools). لحماية المتجر، تقوم بوابة YemenPay بالتحقق الخلفي التلقائي من الأسعار بمطابقة كل منتج في السلة.

كيف يتم تطبيق التحقق في متجرك؟

يجب تضمين وسم ميتا في قسم <head> الخاص بصفحة المتجر لتأكيد السعر الحقيقي والعملة للطلب:

أولاً: وسم HTML Meta

index.html

<html>
  <head>
      <title>عربة التسوق</title>
      <!-- حماية السعر والعملة -->
      <meta name="yemenpay-value" content="37100" data-currency="YER" />
  </head>
  <body>
  ...
  </body>
</html>

حماية طلبات الخصم (Coupons)

عند تطبيق كوبون خصم، استخدم نقطة التحقق في واجهة الـ API أو استخدم الكود الخلفي التالي لتوليد توقيع data-coupon-enc وتمريره باستخدام المفتاح السري (Secret Key).

ثانياً: توليد توقيع الكوبون (Node.js)

couponAuth.js

const crypto = require('crypto');

// This code must run on your backend!
function generateCouponSignature(amount, merchantSecretKey) {
  // Encrypt the amount using RC4 and hex formatting
  const cipher = crypto.createCipheriv('rc4', Buffer.from(merchantSecretKey, 'utf8'), '');
  let signature = cipher.update(amount.toString(), 'utf8', 'hex');
  signature += cipher.final('hex');
  return signature.toUpperCase();
}

// Pass this value to the frontend in `data-coupon-enc`
const couponEnc = generateCouponSignature(20, "merchant_sec_key");
console.log(couponEnc);

حاسبة تشفير الكوبونات (Coupon Encrypter)

قم بتوليد التوقيع المشفر لنسبة خصم الكوبون لإرسالها للواجهة الأمامية في وسم data-coupon-enc.

نسبة الخصم بالـ % (Discount)

المفتاح السري للتاجر (Secret Key)

التوقيع المولد (data-coupon-enc)

059D46BE3411D2BB47611E3691

تخطي حظر جدار الحماية (Cloudflare WAF Rule)

إذا كان خادم متجر التاجر محمياً بواسطة Cloudflare أو جدار نارية مماثل، فقد يمنع زاحف التفتيش الخاص ببوابة YemenPay من قراءة صفحة المنتج. لتخطي هذا الحظر، اتبع الخطوات التالية:

قم بتسجيل الدخول إلى لوحة تحكم Cloudflare.
اذهب إلى Security > WAF > Custom Rules.
أنشئ قاعدة استثناء جديدة (Bypass Rule) بناءً على حقل User-Agent للزاحف:
http.user_agent contains "YemenPay-Verification-Engine"
اضبط الإجراء (Action) إلى Bypass للميزات المطلوبة مثل JS Challenge أو Managed Challenge.