انتقل إلى المحتوى الرئيسي

إيزي كاش (EasyKash)

إيزي كاش صفحة دفع مستضافة مصرية تجمع البطاقات وميزة والمحافظ الإلكترونية وقسائم فوري وأمان النقدية وتقسيط البنوك وخدمات الشراء الآن والدفع لاحقاً (ValU، صحولة، كونتكت، فرصة…) في صفحة واحدة. يدفع المشترون على صفحة إيزي كاش ثم يعودون إلى متجرك. الطرق التي تظهر يحددها ما هو مفعّل على حسابك التجاري في إيزي كاش وليس TakeTheme.

الربط​

الإعدادات ← المدفوعات ← إيزي كاش.

بيان الاعتمادمطلوبأين تجده
مفتاح APIنعملوحة البائع في إيزي كاش ← الإعدادات ← إعدادات التكامل (Cash API)
مفتاح HMAC السرينعمنفس الصفحة؛ يُستخدم للتحقق من إشعارات الدفع القادمة من إيزي كاش
رابط الـ Callback — اختياري، لكن سجّله إذا كنت تبيع بقسائم فوري/أمان

تُنشأ الطلبات عند عودة المشتري من إيزي كاش — تؤكد TakeTheme الدفع عبر واجهة الاستعلام في إيزي كاش أثناء العودة، لذا لا يلزم أي Callback للبطاقات والمحافظ والتقسيط.

الاستثناء هو قسيمة الدفع النقدي (فوري/أمان): يغادر المشتري بالقسيمة ويدفع في منفذ لاحقاً ولا يعود أحد إلى متجرك. عندها لا يمكن إنشاء الطلب إلا عبر Callback إيزي كاش. إذا كنت تقدّم قسائم نقدية، اضبط Callback URL في إعدادات التكامل على:

https://api.taketheme.com/api/v1/payment/webhook/easykash

يجب أن تكون خدمة Direct Payment مفعّلة على حسابك (تواصل مع دعم إيزي كاش إذا لم تجد صفحة إعدادات التكامل).

لا توجد بيئة اختبار منفصلة — تُصدر إيزي كاش بيانات اعتماد اختبارية على نفس نقاط الإنتاج.

الإعدادات​

الإعدادالافتراضيما يفعله
الاسم المعروض عند الدفعفارغالاسم الذي يراه العميل عند الدفع (مثل «بطاقة، محفظة، فوري أو تقسيط»). فارغ = يظهر «EasyKash»
رسوم المعاملةلا شيءرسوم ثابتة أو نسبة تُضاف إلى الطلب عند اختيار هذه الطريقة
إرسال بريد تأكيد الدفعمفعّليرسل بريداً للعميل عند نجاح الدفع
الإشعار عند فشل الدفع (بريد)فارغينبّه فريقك عند فشل عملية دفع
تعليم الطلبات كمدفوعة تلقائياًمفعّلغير مُطبَّق حالياً — الدفع المؤكَّد يعلّم الطلب كمدفوع دائماً

العملة​

تقبل إيزي كاش المبلغ بـ EGP أو USD أو SAR أو EUR أو GBP أو QAR أو AED أو KWD، وترسل TakeTheme عملة متجرك كما هي. يُحاسَب المشتري دائماً بالجنيه المصري بسعر صرف إيزي كاش لحظة الدفع، لذا في متجر بعملة غير الجنيه توقّع أن يختلف المبلغ الذي تبلّغ عنه إيزي كاش عن إجمالي الطلب؛ تسجّل TakeTheme الفرق للمطابقة ولا ترفض الدفع.

المتجر بأي عملة أخرى (مثل OMR) لا يمكنه استخدام إيزي كاش — سيرفض الدفع إنشاء رابط الدفع.

ترفض إيزي كاش أيضاً أي مبلغ 1.00 أو أقل (بالعملة المرسلة). ترفض TakeTheme هذه المبالغ قبل الاتصال بالبوابة برسالة EasyKash requires an amount greater than 1 … — انتبه لذلك عند إنشاء طلبات اختبار.

مسار الدفع​

  1. يختار المشتري إيزي كاش ويُرسل طلب الدفع.
  2. تنشئ TakeTheme رابط Direct Pay بمرجع رقمي customerReference وتحوّل المشتري إلى إيزي كاش.
  3. يدفع المشتري بالبطاقة أو المحفظة أو خطة تقسيط — أو يحصل على قسيمة فوري/أمان ليدفع نقداً لاحقاً (تنتهي القسائم بعد 3 ساعات افتراضياً من جهة إيزي كاش).
  4. تعيد إيزي كاش المشتري إلى TakeTheme (GET /v1/payment/easykash/return). تسأل TakeTheme واجهة Payment Inquiry في إيزي كاش إن كان الدفع PAID — ولا تثق أبداً بمعامل status القادم من المتصفح — وتنشئ الطلب هناك مدفوعاً.
  5. يصل المشتري إلى صفحة النجاح في متجرك ثم إلى صفحة الشكر.

إذا كان رابط الـ Callback مسجّلاً، ترسل إيزي كاش أيضاً تأكيداً موقّعاً:

POST https://<your-api-host>/api/v1/payment/webhook/easykash

التحقق من التوقيع إلزامي على الـ Callback. يحمل كل إشعار signatureHash محسوباً بـ HMAC-SHA512 بمفتاحك السري؛ الإشعار غير الموقّع أو غير المطابق يُرفض بـ 403 ولا يُسجَّل شيء. تُطابَق الإشعارات مع الدفعة عبر customerReference ومزوّد الخدمة معاً، والإشعار لدفعة أُكِّدت مسبقاً في مسار العودة يُقبل ويُتجاهل — أيهما يصل أولاً ينشئ الطلب، ولا ينشئه كلاهما.

المدفوعات الفاشلة والمهجورة​

ترسل إيزي كاش إشعاراً عند النجاح فقط. البطاقة المرفوضة أو الصفحة المهجورة تعيد المشتري إلى متجرك بـ status=failed حيث يرى فشل الدفع ويمكنه المحاولة مجدداً؛ ويُعلَّم سجل الدفع كفاشل عندما يبلّغ استعلام إيزي كاش بذلك. قسيمة الدفع النقدي غير المدفوعة تبقى معلّقة حتى تنتهي — ولا يُنشأ لها طلب.

المرتجعات​

تُسجَّل المرتجعات في TakeTheme فقط — لا يُرسل أي طلب استرداد إلى إيزي كاش. نفّذه من لوحة إيزي كاش وسجّله هنا. راجع المرتجعات.

حل المشكلات​

دُفعت قسيمة فوري/أمان ولم يظهر طلب. تكتمل مدفوعات القسائم بعد مغادرة المشتري، فلا يمكن إنشاء الطلب إلا عبر الـ Callback — سجّل رابط الـ Callback أعلاه.

تُرفض الإشعارات بـ 403. مفتاح HMAC المحفوظ لا يطابق المفتاح الذي توقّع به إيزي كاش. أعد كتابته كاملاً — القيم المخفية تُتجاهل عند الحفظ.

يفشل الدفع برسالة «EasyKash does not support …». عملة متجرك ليست من العملات الثماني التي تقبلها إيزي كاش. تُقفل عملة المتجر بعد أول طلب، فاحسم ذلك قبل الإطلاق.

طريقة دفع غير موجودة في صفحة إيزي كاش. تُفعَّل الطرق لكل حساب تجاري من جهة إيزي كاش؛ لا ترسل TakeTheme أي تصفية للطرق.

ذات صلة​