يتيح «سوق» طريقتي دفع عند إتمام الطلب، يختار العميل إحداهما، وتفعّل أنت كل واحدة أو توقفها من اللوحة > الإعدادات > الطلبات والدفع.
الدفع عند الاستلام
مفعّل افتراضيًا. يُنشأ الطلب بحالة جديد / غير مدفوع، وحين تنقله إلى تم التسليم تصبح حالة دفعه مدفوع (فقد استلم المندوب المبلغ نقدًا).
الدفع بالبطاقة عبر ثواني
ثواني بوابة دفع عُمانية تقبل البطاقات المحلية والدولية بالريال العماني.
الإعداد
افتح حساب تاجر لدى «ثواني» واحصل على المفتاح السري والمفتاح العام، وتوفر «ثواني» مفاتيح اختبار لبيئة UAT أيضًا.
ضعهما في
.env:THAWANI_MODE="uat" # "live" للمدفوعات الحقيقية THAWANI_SECRET_KEY="..." THAWANI_PUBLISHABLE_KEY="..." SITE_URL="https://shop.example.om"أعد تشغيل الخادم، ثم فعّل الدفع بالبطاقة في الإعدادات. تخبرك صفحة الإعدادات إن وُجد المفتاحان.
لا يظهر الدفع بالبطاقة إلا إذا وُجد المفتاحان، وكان الخيار مفعّلًا، وكانت عملة المتجر الريال العماني.
ماذا يحدث أثناء الدفع
- يرسل العميل الطلب باختيار البطاقة، فيسعّره الخادم ويخصم المخزون ويحتسب الكوبون تمامًا كما في الدفع النقدي، ويُنشئ الطلب بحالة جديد / غير مدفوع.
- يفتح الخادم جلسة دفع لدى «ثواني» بإجمالي الطلب (بالبيسة) ويوجّه العميل إلى صفحة الدفع لديها. لا يرى موقعك رقم البطاقة إطلاقًا.
- تعيد «ثواني» العميل إلى
/api/payments/thawani/return?order=CODE. - لا يثق الخادم بهذا الرابط: بل يسأل «ثواني» عن حالة الجلسة بالمفتاح السري، ولا يصبح الطلب مدفوعًا إلا إذا أجابت «ثواني» بأنه دُفع (مع قيد في السجل «تأكد الدفع بالبطاقة»).
- إن ألغى العميل الدفع في صفحة «ثواني» يُلغى الطلب ويعود مخزونه واستخدام الكوبون.
إن تعذّر الوصول إلى «ثواني» لحظة الطلب، يُلغى الطلب فورًا ويرى العميل أن الدفع بالبطاقة غير متاح الآن، فيستطيع اختيار الدفع النقدي.
حالات طلبات البطاقة
طلب البطاقة غير المدفوع لا يملك الموظف إلا إلغاءه، فهو يتقدم وحده حين يتأكد الدفع. وإن أُوقف طلب مدفوع قبل الشحن فإنه يصبح مستردًّا لا ملغى (أعِد المبلغ للعميل من بوابة «ثواني»).
الاختبار
مع THAWANI_MODE="uat" استخدم بطاقات الاختبار المذكورة في توثيق «ثواني». صفحة الطلب تُحدّث نفسها كل بضع ثوانٍ وهي تنتظر الدفع.
بوابة دفع أخرى
كود الدفع في src/lib/thawani.ts (دالتان: إنشاء جلسة وقراءة حالتها) وفي src/app/api/payments/thawani/return/route.ts. لاستخدام بوابة أخرى اكتب الدالتين نفسيهما لها، والتزم القاعدة: لا تعلّم الطلب مدفوعًا إلا بعد سؤال البوابة من الخادم.