تخطي إلى المحتوى
دليل

التعامل مع الاسترداد والدفعات الخاطئة في شام كاش وسيريتل كاش

بقلم فايز الشامينُشر: قراءة لمدة 6 دقائق
الخلاصة

المبالغ الخاطئة والعمليات المكررة تُعلَّق للمراجعة ولا تُشحن تلقائيًا. رقم العملية يُستهلك مرة واحدة لكل محفظة. الاسترداد يخرج من تطبيق المحفظة ويُسجَّل في المتجر برقم عملية الإخراج، دون ادعاء مسار API رسمي للإعادة.

متى تظهر المشكلة

زبون يدفع 50,000 والمطلوب 45,000. زبون آخر يحوّل مرتين لأن التأكيد تأخر دقيقة. ثالث يرسل رقم عملية يخص تحويلًا قديمًا. في المتاجر التي أربطها بشام كاش أو سيريتل كاش، هذه الحالات تظهر في التشغيل. تحويل المحفظتين ما فيه حقل ملاحظة، فالمطابقة لا تعتمد على أن يكتب الزبون رقم الطلب داخل التحويل. تعتمد على رقم العملية والمبلغ، وعلى نظام يسجّل ما حدث عندما لا يتطابق الاثنان.

لا أتكلم باسم شام كاش ولا باسم سيريتل كاش. رسوم الاسترداد، والمهل، وحدود الحساب، وشروط قبول الإعادة، هذه بينك وبين المحفظة، وقد تتغيّر. ما أكتبه هنا تشغيلي: كيف يكتشف متجرك الدفعة الخاطئة، كيف تمنع استخدام رقم العملية مرتين، وكيف تسجّل إعادة المبلغ بعد أن ترسلها أنت من التطبيق إذا قررت ذلك. لا أخترع مسارًا رسميًا للاسترداد غير موجود في اتفاقك مع المحفظة، ولا أضع أرقامًا لحدود الاستلام.

ربط المحفظة نفسه للمتجر مشروح في كيف تربط شام كاش API بمتجرك وفي كيف تربط سيريتل كاش بمتجرك الإلكتروني. الفرق بين التأكيد اليدوي والتلقائي على ووكومرس موجود في سيريتل كاش على ووكومرس: يدوي أم تلقائي؟. هنا أبقى عند ما بعد الدفع: عندما تصل العملية والمبلغ لا يوافقان الطلب.

ماذا يطابق النظام، وماذا يحفظ فقط

المطابقة شرط واضح: رقم العملية لم يُستخدم من قبل، والمبلغ يساوي مبلغ الطلب المفتوح الذي تربطه به. رقم المرسل يعود دائمًا مع التحويل، وأحفظه مع السجل. لا أستخدمه مفتاحًا للمطابقة. الزبون قد يدفع من رقم ابنه أو من حساب آخر في العائلة.

إذا نجح الشرط، تُعلَّم الطلب مدفوعًا ويُحفظ رقم العملية عليه. إذا فشل، الطلب يبقى غير مشحون، وتُفتح حالة للمراجعة. الشحن قبل المراجعة هو أغلى خطأ في هذا المسار.

حالات أراها في التشغيل

المبلغ أقل من المطلوب. لا أشحن. إمّا أن يطلب المتجر تتمة المبلغ بتحويل ثانٍ برقم عملية جديد، أو يعيد المبلغ كاملًا ويبدأ الطلب من جديد. هذا قرار التاجر، ويُكتب في رسالة واضحة للزبون حتى لا يُفهم على أنه قاعدة المحفظة.

المبلغ أكبر من المطلوب. لا أعتبر الزيادة عربونًا صامتًا، ولا أكمل الطلب وكأن شيئا لم يحدث من دون علم التاجر. السجل يُعلَّم «مبلغ زائد»، ويقرر التاجر: شحن مع إعادة الفرق، أو إعادة الكل، أو اتفاق آخر مع الزبون. من دون هذا العلم، الفرق يضيع في الحساب ويظهر لاحقًا كشكوى.

رقمان مختلفان لنفس المبلغ من نفس الزبون، والطلب كان بانتظار تأكيد. هذا غالبًا دفع مكرر لأن الرسالة تأخرت أو لأن الزبون حوّل مرتين. أحد الرقمين يُربط بالطلب، والثاني يُعلَّم للمراجعة وقد يستحق إعادة. لا أربط الرقمين بنفس الطلب على أنهما دفعة واحدة من دون مراجعة.

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

رقم عملية صحيح ومربوط أصلًا بطلب آخر. الرفض هنا واجب. إعادة استخدام الرقم هي الطريق السريع لشحن طلبين مقابل تحويل واحد.

هذه الحالات نفسها تظهر داخل بوت واتساب أو تيليغرام، لا في صفحة الدفع وحدها. تدفق الطلب في المحادثة مشروح في بوت واتساب للطلبات والدفع بشام كاش. القاعدة لا تتغيّر مع القناة.

الاسترداد كما أسجّله في النظام

عندما يقرر التاجر إعادة مبلغ، الإعادة تتم من تطبيق المحفظة أو من إجراءاتها المعتادة، حسب ما تتيحه له محفظته في ذلك الوقت. نظام المتجر لا يخترع زرًا للاسترداد الرسمي إذا لم تكن هذه القدرة موجودة في اتفاقك. ما يفعله النظام: يمنع شحن الطلب، يسجّل سبب الإعادة، ويحفظ رقم عملية الإرسال عندما يُعيد التاجر المبلغ ويكتب هذا الرقم. بعدها لا يبقى الطلب معلّقًا بلا نهاية، ولا تُنسى عملية خرجت من الحساب من دون أثر.

لا أعد بأوقات وصول، ولا بنسبة رسوم، ولا بأن الإعادة دائمًا فورية. إذا كانت المحفظة تقتطع رسمًا أو تتأخر، هذا يظهر في تطبيق التاجر، وأذكره للزبون بصيغة عامة حتى يراجع حسابه، من دون أن أنسب للمحفظة رقمًا لم تؤكده.

سياسة المتجر نفسها (متى تعيد، ومتى لا تعيد بعد الشحن) تُكتب في صفحة الشراء أو في رسالة البوت قبل الدفع. النظام ينفّذ ما قررته أنت، ولا يخترع سياسة باسم شام كاش أو سيريتل كاش.

كود السجل الذي أستخدمه لهذا

القيد الفريد على رقم العملية داخل نفس المحفظة هو أساس الحماية. جدول للدفعات الواردة، وجدول لحالات المراجعة، وحقل لرقم عملية الإعادة إذا خرج المبلغ.

```python from dataclasses import dataclass from datetime import datetime, timezone import psycopg

@dataclass class Incoming: wallet: str # sham_cash or syriatel_cash transaction_id: str amount: int sender: str | None

class PaymentError(Exception): pass

def apply_payment(conn, order_id: int, expected_amount: int, incoming: Incoming) -> str: now = datetime.now(timezone.utc) try: with conn.transaction(): existed = conn.execute( """ SELECT order_id FROM incoming_payments WHERE wallet = %s AND transaction_id = %s """, (incoming.wallet, incoming.transaction_id), ).fetchone() if existed: raise PaymentError("transaction_id_already_used")

order = conn.execute( """ SELECT id, status FROM orders WHERE id = %s FOR UPDATE """, (order_id,), ).fetchone() if not order or order["status"] != "awaiting_payment": raise PaymentError("order_not_awaiting_payment")

conn.execute( """ INSERT INTO incoming_payments (wallet, transaction_id, amount, sender, order_id, received_at) VALUES (%s, %s, %s, %s, %s, %s) """, (incoming.wallet, incoming.transaction_id, incoming.amount, incoming.sender, order_id, now), )

if incoming.amount == expected_amount: conn.execute( "UPDATE orders SET status = 'paid', paid_at = %s WHERE id = %s", (now, order_id), ) return "paid"

reason = "amount_low" if incoming.amount < expected_amount else "amount_high" conn.execute( "UPDATE orders SET status = 'needs_review' WHERE id = %s", (order_id,), ) conn.execute( """ INSERT INTO payment_reviews (order_id, transaction_id, wallet, expected_amount, actual_amount, reason, created_at) VALUES (%s, %s, %s, %s, %s, %s, %s) """, (order_id, incoming.transaction_id, incoming.wallet, expected_amount, incoming.amount, reason, now), ) return "needs_review" except psycopg.errors.UniqueViolation: raise PaymentError("transaction_id_already_used")

def record_refund(conn, order_id: int, refund_transaction_id: str, amount: int, note: str) -> None: """Record a refund already sent from the wallet app. Does not call a wallet API.""" with conn.transaction(): conn.execute( """ INSERT INTO refunds (order_id, refund_transaction_id, amount, note, recorded_at) VALUES (%s, %s, %s, %s, %s) """, (order_id, refund_transaction_id, amount, note, datetime.now(timezone.utc)), ) conn.execute( "UPDATE orders SET status = 'refunded' WHERE id = %s", (order_id,), ) ```

وفي قاعدة البيانات:

```sql CREATE UNIQUE INDEX incoming_payments_one_use ON incoming_payments (wallet, transaction_id);

CREATE UNIQUE INDEX refunds_one_out ON refunds (refund_transaction_id); ```

apply_payment لا يشحن البضاعة. يغيّر حالة الطلب فقط. الشحن خطوة لاحقة بعد الحالة paid. record_refund لا يرسل مالًا؛ يسجّل رقم العملية بعد أن تُعيد أنت المبلغ. إذا حاول أحد إدخال نفس رقم الوارد مرتين، القيد يوقفه.

رقم المرسل يُحفظ في العمود sender ويظهر في شاشة المراجعة. الموظف قد يستفيد منه عندما يقول الزبون «دفعت من رقم أخي». يبقى رقم العملية والمبلغ هما الشرط.

ماذا تقول للزبون، وما لا تقوله

رسالة «المبلغ لا يطابق الطلب، الطلب لم يُشحن، سنراجع العملية» أوضح من اعتذار بلا سبب. إذا طلبت رقم العملية من جديد، اذكر أن التحويل ما فيه حقل ملاحظة، وأن الرقم يظهر بعد نجاح الدفع.

لا تَعِد بتاريخ إعادة محدد باسم المحفظة إذا لم يكن عندك هذا الرقم منها. لا تكتب في الشات أن «النظام استرد المبلغ تلقائيًا» إذا كانت الإعادة قد خرجت يدويًا من تطبيقك. الوضوح هنا يختصر جدالًا لاحقًا.

أسئلة تتكرر

هل أقدر أرجع المبلغ تلقائيًا من الـAPI؟

لا أبني المقالة على وجود مسار استرداد برمجي رسمي. إذا قررت الإعادة، تتم من أدوات المحفظة المتاحة لك، ثم يُسجَّل رقم عملية الإخراج في نظام المتجر.

هل رقم المرسل يكفي لأربط الدفعة بالطلب؟

لا. رقم المرسل يعود دائمًا وأحفظه. المطابقة برقم العملية والمبلغ.

ماذا لو دفع الزبون ورسائل التأكيد تأخرت فدفع ثانية؟

الطلب يُربط برقم واحد. الرقم الثاني يبقى في المراجعة حتى تقرر إعادة المبلغ أو لا.

هل أكتفي بلقطة الشاشة إذا كان المبلغ ظاهرًا؟

لا للشحن. لقطة الشاشة مساعدة للمراجعة. التنفيذ بعد التحقق من رقم العملية والمبلغ عبر البوابة.

من يتحمل فرق الرسم إذا اقتطعت المحفظة شيئًا عند الإعادة؟

هذا يرجع لاتفاقك مع المحفظة ولسياسة متجرك المكتوبة قبل البيع. لا أثبت هنا رسمًا أو نسبة.

إذا بدك بوابة دفع لشام كاش وسيريتل كاش، مع سجل للمراجعة والإعادة كما فوق، راسلني من صفحة الموقع أو على fayezalshami.dev@gmail.com. اذكر نوع المحفظة، ومنصة المتجر أو البوت، وكيف تريد أن تُعالج المبالغ غير المطابقة.

بقلم فايز الشامي | Fayez Alshami، مطور باك إند وبوابات دفع سيريتل كاش وشام كاش.

أدلّة ومقارنات

تحتاج إلى بناء هذا أو ربطه لعملك؟

استعرض الخدمات