توثيق الـ API · v2

دمّج MIHWAR في مشروعك في عشر دقايق.

كل عملية إيداع بتبدأ من الـ API بتاعك، وتمشي على مخزون الشبكة بتاعنا. العميل بيوافق على موبايله، والرصيد بيتضاف في حسابك على المنصة تلقائياً، وإنت بتعرف بالـ webhook أو بالسؤال عن المرجع.

عنوان الـ API

https://gate.kinghelm.xyz/api/v2

ابدأ من هنا

أبسط دمج كامل

تلات خطوات: اعمل العملية، اسأل عنها بمرجعك إنت، واستقبل الإشعار. المفاتيح بتلاقيها في صفحة مفاتيحي.

١ أنشئ العملية

curl -X POST "https://gate.kinghelm.xyz/api/v2/payment/create" \
  -H "Authorization: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "ORD-1042", "number": "01012345678",
         "amount": 150, "method": "vf_cash" }'

٢ العميل يوافق على موبايله — وبعدها اسأل

curl -X POST "https://gate.kinghelm.xyz/api/v2/payment/confirm" \
  -H "Authorization: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "ORD-1042" }'

٣ خلّي التاجر يعرف — webhook أو استعلام

سجّل webhook_url وقت الإنشاء، وهيوصلك transaction.completed موقّع. أو اسأل بنفسك بأي وقت بـ order_id أو الـ reference.

202 · MH-4031 في الخطوة ٢ معناه العميل لسه ما وافقش — كرّر السؤال بعد ثوانٍ، أو استنى الـ webhook.

المصادقة

مفتاحين بس

عام

pk_…

للـ wallets، payment/create، payment/confirm. ينفع من المتصفح ومن السيرفر.

سري

sk_…

لـ payment/info بس. يتحقن مرة واحدة في الحياة وما بيترشّحش تاني. مكانه سيرفرك بس.

Authorization: pk_live_xxx
Authorization: Bearer pk_live_xxx — accepted too

المفتاح يشتغل زي ما هو في الهيدر، وبنقبل Bearer كمان لو معتاد في HTTP clients بتاعتك.

حدود المعدل (per minute)

60 طلب لكل مفتاح · 120 لكل IP · 30 إنشاء طلب · 1 إنشاء لكل رقم في الدقيقة.

المفتاح الخاطئ

10 محاولات خاطئة من نفس IP خلال 5 دقايق → 429 · MH-2004 لباقي المدة.

الـ endpoints

أربع مسارات بس

قائمة المحافظ المتاحة

GET /api/v2/wallets

عام

curl "https://gate.kinghelm.xyz/api/v2/wallets" \
-H "Authorization: pk_live_xxx"

{
  "success": true,
  "code": "MH-2000",
  "data": { "wallets": [{
    "method": "vf_cash",
    "label": "فودافون كاش",
    "number_pattern": "^010[0-9]{8}$",
    "min_amount": 5,
    "max_amount": 10000,
    "supports_deposit": true,
    "supports_withdraw": true
  }] },
  "errors": null,
  "meta": { "api_version": "v2", "request_id": "req_…", "timestamp": "…" }
}

إنشاء عملية إيداع

POST /api/v2/payment/create

عام

بيبعت طلب تأكيد ( USSD) على موبايل العميل لرقم المحفظة اللي انت بعته. لسه مفيش فلوس بتحرك — الفلوس بتتحرك بس لما العميل يوافق على موبايله، وساعتها بتتأكد أنت بـ payment/confirm.

curl -X POST "https://gate.kinghelm.xyz/api/v2/payment/create" \
  -H "Authorization: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-1042",
    "number": "01012345678",
    "amount": 250,
    "method": "vf_cash",
    "webhook_url": "https://your-shop.com/hooks/mihwar",
    "customer_name": "أحمد محمد",
    "description": "طلب #1042"
  }'

الحقل	مطلوب	الوصف
order_id	نعم	معرّف طلبك — تكراره بيرجّع نفس العملية بدون خصم جديد (MH-2004)
number	نعم	رقم محفظة العميل
amount	نعم	المبلغ بالجنيه (5 – 10,000)
method	نعم	كود المحفظة من `GET /wallets`
webhook_url	لا	لينك الإشعار — ينفع تبعته في الطلب أو تسيبها
metadata	لا	أي بيانات إضافية (10 حقول كحد أقصى) بترجعلك زي ما هي

HTTP 200
{
  "success": true,
  "code": "MH-2001",
  "message": "أكّد الطلب من محفظتك خلال 60 ثانية.",
  "data": {
    "reference": "MH-7391846205",
    "status": "pending",
    "approve_instruction": "أكّد الطلب من محفظتك خلال 60 ثانية."
  }
}

تأكيد العملية

POST /api/v2/payment/confirm

عام

بيسأل الشبكة: العميل وافق؟ لو آه، الفلوس بتتحصّل ورصيدك على المنصة بيتحدّث في نفس اللحظة (قيد مزدوج كامل). متكرر النداء بأمان — العملية المكتملة هترجع مكتملة. تقدر تبعت order_id بتاعك بدل reference — الاتنين يوصلوا لنفس العملية.

curl -X POST "https://gate.kinghelm.xyz/api/v2/payment/confirm" \
  -H "Authorization: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "MH-7391846205" }'

# أو بمرجعك إنت:
  -d '{ "order_id": "ORD-1042" }'

200 · MH-2003

مكتملة

الفلوس اتحصّلت ورصيدك اتضاف. في الـ data هتلاقي fee وnet وbalance_impact.

202 · MH-4031

لسه معلقة

العميل ما وافقش لسه — أعد المحاولة بعد ثوانٍ.

422 · MH-4032

انتهت المدة

خلصت نافذة الـ 60 ثانية — طلب جديد بـ order_id تاني.

سؤال عن عملية

GET /api/v2/payment/info/{reference}

سرّي

مرجع دائم للعملية مع الحالة والرسوم والصافي. المفتاح السري بس — المفتاح العام بيرفض هنا بالتصميم. المسار {reference} بيفهم كمان order_id بتاعك، وينفع كمان على الـ query string: GET /payment/info?reference=MH-…

curl "https://gate.kinghelm.xyz/api/v2/payment/info/MH-7391846205" \
-H "Authorization: sk_live_xxx"

{
  "success": true,
  "data": {
    "reference": "MH-7391846205",
    "order_id": "ORD-1042",
    "amount": 250.0,
    "status": "completed",
    "method": "vf_cash",
    "fee": 0.0,
    "net": 250.0,
    "balance_impact": 250.0,
    "metadata": { "coupon": "RAMADAN" }
  }
}

الـ webhook

إشعار موقّع بنتيجة العملية

بدل ما تلفّ على payment/info كل شوية، المنصة بتبعت POST لرابطك أول ما العملية تخلص. الأحداث: transaction.completed و transaction.rejected. إعادة المحاولة تلقائية حتى 3 مرات مع backoff أسّي، وبعد كده يفضل dead ظاهر في الكونسول.

الهيدرز

في كل إشعار

Content-Type: application/json
User-Agent: MIHWAR-Webhook/2.0
X-Helm-Event: transaction.completed
X-Helm-Signature-256: 9f86d0… ← hex خام من HMAC-SHA256
X-Helm-Delivery: dlv_… ← نفس القيمة في X-Idempotency-Key
X-Helm-Timestamp: 2026-09-27T18:00:00+02:00

الـ payload

التوقيع بيتحسب على حقل data بس

{
  "event": "transaction.completed",
  "timestamp": "2026-09-27T18:00:00+02:00",
  "data": {
    "reference": "MH-7391846205",
    "order_id": "ORD-1042",
    "amount": 250.0,
    "currency": "EGP",
    "method": "vf_cash",
    "number": "01012345678",
    "status": "completed",
    "fee": 0.0,
    "net": 250.0
  }
}

التحقق من التوقيع

HMAC-SHA256 على: reference | number | amount | method | status

$stringToSign = implode('|', [
  $d['reference'],
  $d['number'],
  rtrim(rtrim(number_format((float) $d['amount'], 2, '.', ''), '0'), '.') ?: '0',
  $d['method'],
  $d['status'],
]);

$expected = hash_hmac('sha256', $stringToSign, $your_secret_key); // sk_… بتاعك
$given = $headers['X-Helm-Signature-256'];

$ok = hash_equals($expected, $given);

المفتاح هو sk_… نفسه بتاعك (مش سر منفصل) — عشان كده مكانه سيرفرك بس. استخدم hash_equals للمقارنة (ثابتة الزمن)، والمقارنة بـ == تفتح timing attack. رجّع 200 بسرعة، واعمل business logic في الخلفية — وإلا التكرار هيوصلك تاني.

الأكواد

كل كود ليه معنى واحد

MH-2001عملية اتعملت — في انتظار موافقة العميل

MH-2003تم التأكيد — الرصيد اتضاف

MH-2004order_id مكرر — مفيش خصم جديد

MH-4001/2مفتاح ناقص أو غلط

MH-4021/22رقم أو مبلغ خارج النطاق

MH-4031لسه بانتظار موافقة العميل (202)

MH-4032/33انتهت المدة / رفض

MH-5001/3المزود رفض أو انتهت الجلسة

والرد نفسه دايماً في نفس الـ envelope: success · code · message · data · errors · meta.

الأسعار

الإيداع

0%

المبلغ كله بيتحسب في حسابك — المنصة بتكسب من السحب.

السحب

1% + 1

بتاخد على الإجمالي، والحد الأدنى 2 ج.م — الرسوم بتظهر في fee وnet في كل عملية.

دمّج MIHWAR في مشروعك في عشر دقايق.

أبسط دمج كامل

مفتاحين بس

pk_…

sk_…

أربع مسارات بس

إشعار موقّع بنتيجة العملية

كل كود ليه معنى واحد

جاهز تبدأ؟