API v1

توثيق API

اربط متجرك أو تطبيقك بـ EasyCash Confirm وأكّد تحويلات فودافون كاش واتصالات كاش برمجياً — بدون ما تحتاج التاجر يفتح الداشبورد بإيده لكل عملية.

البداية السريعة

EasyCash Confirm مش بيحرّك فلوس زي بوابات الدفع التقليدية — الفلوس بتتحرك مباشرة بين محفظتي العميل والتاجر. دورنا إننا نتأكد إن التحويلة فعلاً وصلت، عن طريق مطابقة رقم الهاتف والمبلغ مع رسائل SMS اللي وصلت فعلاً لحساب التاجر.

1. اعرض تعليمات التحويل

في صفحة الدفع، اعرض للعميل رقم المحفظة والمبلغ المطلوب تحويله.

2. العميل يحوّل ويأكد

بعد ما يحوّل فعلياً من تطبيق المحفظة بتاعه، يضغط زرار "تم التحويل" في متجرك.

3. اطلب رقمه والمبلغ

اعرض فورم بسيط: رقم الهاتف اللي حوّل منه + المبلغ — يدخلهم ويأكد.

4. استدعِ /verify

ابعت الرقم والمبلغ لـ EasyCash Confirm، وهيرد عليك فوراً بحالة التحويلة.

المصادقة

كل طلب لازم يحتوي هيدر X-Api-Key بمفتاحك الخاص. تلاقيه في صفحة الإعدادات داخل حسابك — منفصل تماماً عن مفتاح تطبيق الموبايل وعن بيانات دخول لوحة التحكم.

Request header

curl https://easycash.382719465.xyz/api/v1/payments/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

محتفظ بمفتاحك سري — أي حد يعرفه يقدر يستعلم عن تحويلات حسابك. لو اتسرب، ولّد مفتاح جديد فوراً من الإعدادات.

مهم جدًا: استدعِ /verify ومسارات v1 الأخرى من كود سيرفر بتاعك (Node.js، PHP، ...) بس — أبدًا من كود شغّال جوه متصفح العميل (زرار في صفحة الدفع مثلاً). أي كود Frontend/JavaScript شغال في المتصفح هيعرض مفتاح الـ API لأي حد يفتح Developer Tools، ولو مفتاحك اتسرب كده هيقدر يستعلم عن كل تحويلات حسابك.

POST/api/v1/payments/verify

يدوّر على تحويلة وصلت فعلاً لحساب التاجر بنفس الرقم والمبلغ خلال آخر 30 دقيقة. لو لقاها، يأكدها فوراً ويرجّع رقمها كمرجع — نفس التحويلة متقدرش تتأكد مرة تانية بعد كده. تقدر كمان تربطها برقم مرجعي خاص بيك (externalRef) — مش شرط أوردر متجر، ممكن يبقى حجز أو اشتراك أو أي كيان تاني عندك.

بيانات الطلب (Body)

الحقل	النوع	الوصف
phone	string	رقم الهاتف اللي حوّل منه العميل، بنفس صيغة رقم فودافون كاش.
amount	number	المبلغ بالجنيه، لازم يطابق المبلغ المحوّل بالظبط.
externalRef	string (اختياري)	رقم مرجعي حر عندك (أوردر، حجز، اشتراك، أي حاجة) — بيتسجل مع التحويلة ويرجع تاني في أي استعلام لاحق عنها.

Request

curl -X POST https://easycash.382719465.xyz/api/v1/payments/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "01012345678",
    "amount": 250,
    "externalRef": "WOO-1234"
  }'

✓ لو اتأكدت

{
  "ok": true,
  "data": {
    "confirmed": true,
    "reference": "3f7a1c9e-...",
    "amount": 250,
    "confirmedAt": 1723300000000,
    "externalRef": "WOO-1234"
  }
}

لسه مالقاش تطابق

{
  "ok": true,
  "data": {
    "confirmed": false
  }
}

GET/api/v1/payments/:reference

استعلام عن حالة تحويلة معينة بالرقم المرجعي اللي رجعه /verify — مفيد لو محتاج تتأكد تاني بعدين (مراجعة طلب، نزاع، أرشفة) من غير ما تعيد إرسال الرقم والمبلغ تاني ولا ترجع للداشبورد.

Request

curl https://easycash.382719465.xyz/api/v1/payments/REFERENCE \
  -H "X-Api-Key: YOUR_API_KEY"

✓ لو موجودة

{
  "ok": true,
  "data": {
    "reference": "3f7a1c9e-...",
    "status": "confirmed",
    "amount": 250,
    "phone": "01012345678",
    "direction": "in",
    "transferredAt": 1723300000000,
    "externalRef": "WOO-1234"
  }
}

404 — مش موجودة

{
  "ok": false,
  "error": "NOT_FOUND"
}

GET/api/v1/account

يرجّع رقم محفظة الاستلام ونوعها (فودافون كاش / اتصالات كاش) المسجّلين حاليًا في إعدادات حسابك — استخدمه دايمًا لعرض تعليمات التحويل للعميل النهائي، بدل ما تثبّت الرقم يدوي في تكاملك. لو غيّرت رقم محفظتك من لوحة التحكم، أي تكامل بينادي على الإندبوينت ده هياخد الرقم الجديد فورًا من غير أي تعديل في كوده.

Request

curl https://easycash.382719465.xyz/api/v1/account \\
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "ok": true,
  "data": {
    "receiveWalletNumber": "01012345678",
    "receiveWalletProvider": "vodafone_cash"
  }
}

إندبوينت اختبار منفصل

وأنت بتبني تكاملك، استخدم /v1/payments/verify-test بمفتاح API الحقيقي بتاعك عشان تشوف شكل رد القبول والرفض فورًا — إندبوينت منفصل تمامًا عن /verify، مش بيقرا ولا يكتب أي بيانات حقيقية خالص.
مهم: الرقم 01000000001 شغّال بس على الإندبوينت التجريبي ده — لو بعتّه على /verify الحقيقي هيتعامل معاه كرقم تليفون عادي زي أي رقم تاني (يعني مش هيتأكد إلا لو فيه تحويل حقيقي فعلي بيه).

✓ 01000000001 — دايمًا بيرجّع confirmed

{
  "ok": true,
  "data": {
    "confirmed": true,
    "reference": "test-reference",
    "amount": 100,
    "confirmedAt": 1723300000000,
    "externalRef": null
  }
}

أي رقم تاني — دايمًا بيرجّع غير مؤكدة

{
  "ok": true,
  "data": { "confirmed": false }
}

مثال

curl -X POST https://easycash.382719465.xyz/api/v1/payments/verify-test \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"01000000001","amount":100}'

GET/api/v1/health

فحص صحة عام — شغّال من غير أي مصادقة، مناسب لأي أداة Uptime Monitoring. لو بعتّ X-Api-Key معاه، هيتأكدلك كمان إن المفتاح شغال ويوريك شكل رد /verify بالظبط (بيانات وهمية).

Request

curl https://easycash.382719465.xyz/api/v1/health \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "ok": true,
  "status": "operational",
  "time": "2026-08-12T14:30:00.000Z",
  "authenticated": true,
  "sample": { "confirmed": false, "reference": null }
}

Idempotency-Key (اختياري)

لو في احتمال إن الشبكة تقطع وتضطر تعيد نفس الطلب، ابعت هيدر Idempotency-Key بقيمة فريدة لكل محاولة تحويل حقيقية (مش لكل استدعاء). أي إعادة محاولة بنفس القيمة هترجّعلك نفس الرد الأول بالظبط، من غير أي تنفيذ تاني.

Request

curl -X POST https://easycash.382719465.xyz/api/v1/payments/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: order-1234-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"phone":"01012345678","amount":250}'

إضافة ووكوميرس الرسمية

عندك متجر ووردبريس/ووكوميرس؟ مش محتاج تكتب أي كود — الإضافة الجاهزة دي بتضيف طريقة دفع "محفظة" في صفحة الدفع، العميل بيحوّل ويأكد بنفسه، والأوردر بيتنشئ مؤكد فورًا لو التحويل اتلاقى — من غير أي أوردر معلّق من غير تأكيد.

1.الإضافات ← أضف جديد ← رفع الإضافة ← اختار ملف الـ zip ← تفعيل.
2.من ووكوميرس ← الإعدادات ← الدفع، فعّل "EasyCash Confirm — دفع محفظة".
3.من نفس الصفحة، الصق مفتاح الـ API بتاع حسابك واحفظ.

للاختبار قبل التركيب الفعلي: استخدم رقم الموبايل 01000000001 عند "تحقق من التحويل" — بيرجّع مؤكد دايمًا من غير أي تحويل فلوس فعلي (نفس رقم وضع الاختبار في/v1/payments/verify-test).

التكامل مع Shopify

مفيش إضافة رسمية جاهزة من عندنا لشوبيفاي دلوقتي — الـ API نفسها متاحة بالكامل، والربط بيتم عن طريق مطوّر (Custom App خاص بمتجرك) بنفس المفتاح ونفس الإندبوينتس اللي في باقي الصفحة دي.

الفرق حسب باقة متجرك

متجر عادي (Basic / Shopify / Advanced): شوبيفاي مش بتسمح بإضافة مخصصة جوه خطوة الدفع نفسها. الفلو العملي: طريقة دفع "يدوية"، الأوردر يتعمل بحالة غير مدفوع، وفورم التحقق (رقم الموبايل + زرار "تحقق") يظهر على صفحة Order Status مباشرة بعد إتمام الطلب.

Shopify Plus: ممكن إضافة مخصصة جوه خطوة الدفع نفسها (زي فلو ووكوميرس تقريبًا) — تعقيد تطوير أكبر، ومحتاج خبرة بـ Checkout UI Extensions.

الإمكانيات دي بتتغيّر من عند شوبيفاي مش من عندنا، فالتفاصيل التقنية الدقيقة (نوع الإضافة المناسبة، حدود الباقة) مسؤولية المطوّر اللي بيبني التكامل حسب أحدث توثيق شوبيفاي وقت التنفيذ. الإندبوينتس اللي هيحتاجها: /verify و/account (لعرض رقم المحفظة تلقائيًا) و/v1/payments/verify-test للاختبار.

الأخطاء والحدود

أي خطأ بيرجع بنفس الصيغة: { "ok": false, "error": "..." }

الحالة	الكود	المعنى
400	INVALID_PAYLOAD	الرقم أو المبلغ ناقص أو غير صالح.
401	UNAUTHENTICATED	مفتاح API غلط أو مش موجود في الهيدر.
402	SUBSCRIPTION_EXPIRED	اشتراك الحساب منتهي — جدّده من لوحة التحكم.
429	RATE_LIMITED	تجاوزت 60 طلب في الدقيقة على نفس مفتاح الـ API — قلّل معدل الطلبات وحاول تاني.

نافذة البحث: التحقق بيدوّر بس في آخر 30 دقيقة من وقت التحويلة. لو العميل حوّل قبل كده بوقت أطول، اطلب منه يحوّل تحويلة جديدة أو تواصل معاك يدوياً.