MAN API

عنوان الخدمة

https://api.man.ps/api/v1

كل استجابة تتضمن X-Request-Id. احتفظ به عند مراجعة أي عملية.

00

فحص هوية المشترك والجاهزية

GET /api/v1/merchant

يعيد هوية المشترك وحدوده وحالة جاهزية مفتاح MAN الحالي، دون كشف أي بيانات تشغيل داخلية.

01

المصادقة والتوقيع

تزودك إدارة MAN بمفتاح API وسر مستقل لمشروعك. احتفظ بالسر داخل Backend فقط.

Accept: application/json
Content-Type: application/json
X-Api-Key: <api_key>
X-Timestamp: <unix_seconds>
X-Signature: <hmac_sha256_hex>
Idempotency-Key: <unique_payment_key>

نص التوقيع يتكون من أربعة أسطر:

METHOD
/api/v1/path
timestamp
sha256(raw_json_body)

Node.js

const crypto = require('crypto');

function sign(method, path, rawBody, timestamp, secret) {
  const bodyHash = crypto.createHash('sha256').update(rawBody).digest('hex');
  const payload = [method.toUpperCase(), path, timestamp, bodyHash].join('\n');
  return crypto.createHmac('sha256', secret).update(payload).digest('hex');
}

02

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

POST /api/v1/payments

{
  "amount": "5.00",
  "currency": "ILS",
  "mobile": "0591234567",
  "external_reference": "ORDER-1001",
  "description": "Internet card"
}

يرسل مشروعك الطلب إلى MAN API فقط، وتتولى MAN تنفيذ المسار المعتمد لهذا المشترك. إذا أصبحت الحالة otp_sent اطلب من العميل إدخال الرمز. لا تسلّم المنتج في هذه المرحلة.

03

تأكيد OTP

POST /api/v1/payments/PAY-REFERENCE/confirm

{ "otp": "12345" }

عند paid يصبح التسليم ready. يسلم مشروع المشترك المنتج ثم يرسل إقرار التسليم إلى MAN.

04

فحص العملية وإلغاؤها

GET  /api/v1/payments/PAY-REFERENCE
POST /api/v1/payments/PAY-REFERENCE/cancel

استخدم الفحص كحل احتياطي إذا تأخر Webhook. لا يمكن إلغاء عملية مدفوعة.

05

حالات الدفع

عند paid تصبح العملية جاهزة للتسليم، وتظهر في تقارير المشترك وفق إعداداته المعتمدة لدى MAN.

06

إقرار تسليم المنتج

بعد الدفع الناجح يسلّم Backend المشترك البطاقة أو الخدمة، ولا يرسل اسم مستخدم البطاقة أو كلمة مرورها إلى MAN. يرسل فقط مرجع التسليم والحالة.

POST /api/v1/payments/PAY-REFERENCE/fulfillment
Idempotency-Key: ORDER-1001-DELIVERY-1

{
  "status": "delivered",
  "delivery_reference": "CARD-DELIVERY-1001"
}

الحالات المسموحة من المشروع هي processing وdelivered وfailed. عند الفشل أرسل failure_reason. إذا تأخر الإقرار تتحول الحالة إلى review وتظهر في لوحة الإدارة لإعادة المحاولة.

07

Webhooks

تصل أحداث الدفع والتسليم إلى رابط شبكتك موقعة بالسر الذي ظهر عند إنشاء Webhook. الحدث fulfillment.ready هو إشارة بدء التسليم.

X-Payment-Webhook-Event: fulfillment.ready
X-Payment-Webhook-Timestamp: 1788370000
X-Payment-Webhook-Signature: <signature>

تحقق من التوقيع باستخدام النص الخام كما وصل:

hmac_sha256(timestamp + "." + raw_json_body, webhook_secret)

أعد أي حالة HTTP من 200 إلى 299. تعيد MAN API المحاولة تلقائيًا عند الفشل.

08

الأخطاء المهمة