حالات المعاملات
لكل صف معاملة في لوحة التحكم واحدة من هذه الحالات. وتعكس الحالة أحدث حدث لتلك المعاملة؛ وتحدّث المبالغ المستردة والنزاعات الصف القائم بدلاً من إدراج صف شقيق.
| الحالة | المعنى |
|---|---|
succeeded | اكتملت الدفعة. المال في حسابك (بعد رسوم المزود). |
pending | الدفعة في طريقها. شائع مع طرق الدفع غير المتزامنة (ACH، وبعض وسائل العملات الرقمية) حيث يستغرق التأكيد دقائق إلى ساعات. |
failed | لم تكتمل الدفعة: رُفِضت البطاقة، أو انتهت صلاحية التفويض، أو رفض صريح. لم يتحرك مال. |
partial | دفع المشتري أقل من المُفوتَر (شائع حين يرسل مشترٍ عملة رقمية مبلغاً مخفَّضاً برسوم الشبكة). يعكس amount الصف ما استُلِم فعلاً؛ افحص metadata.invoicedAmount لما طُلِب. |
refunded | أُعيد المال إلى المشتري، كلياً أو جزئياً. وamount الصف هو المبلغ المسترد؛ ويمكن أن تحدث المبالغ المستردة بعد أيام أو أسابيع من الدفعة الأصلية. |
disputed | فتح المشتري (أو مصرفه) نزاعاً أو استرداداً قسرياً. افحص واجهة المزود لنافذة الرد. ويحمل metadata.reason الصف تصنيف المزود حرفياً. |
pending_manual | معاملة دفع بالبريد تنتظر تأكيدك المادي. انظر القسم التالي. |
manual_canceled | نقرت إلغاء على صف دفع بالبريد معلّق قبل وصول دفعة المشتري. |
manual_expired | بقي صف دفع بالبريد معلّق لمدة 30 يوماً دون تأكيد وانتهت صلاحيته تلقائياً. |
manual_revoked | أكّدت استلام دفعة دفع بالبريد لكنك تراجعت لاحقاً عن التأكيد (مثلاً تبيّن أن الدفعة غير صالحة). ينتقل الصف من succeeded عودةً إلى هذه الحالة النهائية. |
المبالغ المستردة، والنزاعات، والدفعات الجزئية
ينصت Coin Moebius لأحداث المزود هذه ويحدّث صف المعاملة الأصلي في لوحة التحكم. وتحديداً:
- المبالغ المستردة: حدث
charge.refundedفي Stripe (مبالغ مستردة كلية أو جزئية، بما فيهاamount_refundedلتُظهر المبالغ المستردة الجزئية الشريحة التي أُعيدت). وrefundedIPN لـ NOWPayments. تنقلب حالة الصف إلىrefunded، ويعكسamountالمبلغ المسترد، ويحملmetadata.originalChargeId/metadata.originalAmountسياق الدفعة الأصلية. - النزاعات (الاسترداد القسري): حدث
charge.dispute.createdفي Stripe. تنقلب حالة الصف إلىdisputed. ويمرّ السبب المذكور من المزود إلىmetadata.reasonحرفياً، ويمكنك تصييره في واجهتك الخاصة كما تشاء. - الدفعات الجزئية:
partially_paidIPN لـ NOWPayments. تنقلب حالة الصف إلىpartial. ويعكسamountما استُلِم فعلاً (actually_paid)؛ وmetadata.invoicedAmountهو ما طُلِب.
في الإصدار الأول، تُعرَض هذه الأحداث في لوحة التحكم وعبر نقطة نهاية /status. وسيضيف إصدار مستقبلي إشعارات بريد إلكتروني ومُحوِّل webhook صادراً ليتفاعل خادمك الخلفي تلقائياً. وفي الوقت الحالي، أعِدّ مهمة استطلاع صغيرة (انظر القسم التالي) أو تحقق من لوحة التحكم.