# كيف تعمل المدفوعات

نيات الدفع والمحاولات، والحالات التي تمر بها الدفعة، والإشارة التي تثق بها قبل تسليم الطلبية.

كل دفعة، بالبطاقة أو نقدًا، هي **نية دفع** (payment intent): كائن واحد لمبلغ واحد تريد تحصيله، من
إنشائه إلى استلام المال. تنشئها بنفسك، أو تنشئها لك جلسة دفع (checkout session) أو رابط دفع. يخبرك
حقلها `status` أين وصلت؛ ويقرؤه كودك بدل التخمين.

## نيات الدفع والمحاولات

يمكن تجربة نية الدفع أكثر من مرة. كل تجربة هي **محاولة**، وتسمى أيضًا **charge**
(`ch_…`): صفحة دفع بالبطاقة فُتحت، أو رمز دفع نقدي أُصدر. رفض البطاقة أو انتهاء صلاحية الرمز ينهي
المحاولة لا نية الدفع: يمكن لعميلك أن يحاول من جديد، بالطريقة نفسها أو بغيرها.

* يشير الحقل `latest_charge` في نية الدفع إلى أحدث محاولة لها.
* تنجح نية الدفع **مرة واحدة**. وحتى إن وصلنا التأكيد عدة مرات، فهناك نجاح واحد، وحدث
  `payment_intent.succeeded` واحد، وقيد واحد في رصيدك.
* يُحدَّد `amount_received` عند نجاح الدفعة؛ ويزداد `amount_refunded` مع كل استرداد.

## دورة الحياة

حالات نية الدفع:

- `requires_payment_method` → `requires_action`: صفحة البطاقة أو رمز الدفع النقدي
- `requires_action` → `processing`: دفع العميل
- `processing` → `succeeded`: تأكيد ومبلغ مطابق
- `requires_action` → `requires_payment_method`: رفض أو فشل أو انتهاء صلاحية
- `processing` → `requires_payment_method`
- `requires_payment_method` → `canceled`: إلغاء أو انتهاء صلاحية
- `requires_action` → `canceled`: تلغيها أنت

قد تنتقل الدفعة بالبطاقة التي تُؤكَّد فورًا من `requires_action` إلى `succeeded` مباشرة.

## كل حالة وما عليك فعله

| الحالة                    | ما تعنيه                                                                                  | ما تفعله                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `requires_payment_method` | لا دفع جارٍ: أُنشئت الدفعة للتو، أو فشلت المحاولة الأخيرة.                                | أرسل عميلك ليدفع، أو دعه يحاول من جديد. يوضح `last_payment_error` سبب فشل المحاولة الأخيرة. |
| `requires_action`         | على عميلك أن يتصرف: يكمل الدفع في صفحة الدفع بالبطاقة، أو يسدد رمز الدفع النقدي لدى وكيل. | انتظر. وإن كانت الصفحة صفحتك، فاعرض `next_action` (انظر أدناه).                             |
| `processing`              | دفع عميلك؛ والتأكيد في الطريق.                                                            | انتظر إشعار الـ webhook. لا تسلّم الطلبية بعد.                                              |
| `succeeded`               | تم تأكيد الدفعة والمبلغ مطابق.                                                            | سلّم الطلبية. هذه الحالة نهائية.                                                            |
| `canceled`                | ألغيتَ الدفعة، أو انتهت صلاحية جلسة الدفع الخاصة بها دون دفع.                             | لا شيء: لا تتحرك أي أموال. أنشئ دفعة جديدة إن عاد عميلك.                                    |

### عندما لا يتطابق شيء

إذا تأكدت دفعة بمبلغ غير المبلغ المطلوب، أو وصل المال بعد إلغاء الدفعة أو انتهاء صلاحية رمزها، فلا
يُضاف شيء إلى رصيدك تلقائيًا. تبقى نية الدفع في `processing` ويُضاف إليها كائن `review`، وتكون
قيمة `reason` فيه `amount_mismatch` أو `paid_after_end`، وتتلقى الحدث `review.opened`. ثم ينظر فيها
أحد أعضاء فريقنا. وفي بيئة الاختبار، تتيح لك [سيناريوهات الدفع النقدي](https://pay-docs.adpromax.com/ar/sandbox/cash-scenarios)
إحداث الحالتين.

## المحاولات

تكون قيمة `status` للمحاولة `pending` أو `succeeded` أو `failed` أو `canceled` أو `expired`. تحمل
المحاولة الفاشلة `failure_code` و`failure_message`، وتنسخهما نية الدفع إلى
`last_payment_error`:

| الرمز                   | طريقة الدفع    | ما حدث                                                             |
| ----------------------- | -------------- | ------------------------------------------------------------------ |
| `card_declined`         | البطاقة        | رفض البنك. وقد يوضح `decline_code` أكثر، مثل `insufficient_funds`. |
| `expired_card`          | البطاقة        | انتهت صلاحية البطاقة.                                              |
| `authentication_failed` | البطاقة        | لم ينجح التحقق عبر 3-D Secure.                                     |
| `processing_error`      | البطاقة، النقد | تعذّرت معالجة الدفعة. يمكن لعميلك أن يحاول من جديد.                |
| `voucher_expired`       | النقد          | لم يُسدَّد الرمز قبل أجله.                                         |
| `voucher_refused`       | النقد          | رفضت شبكة الدفع الرمز.                                             |

للمحاولة عمر محدود: نحو 30 دقيقة لصفحة الدفع بالبطاقة، وأجل الرمز في الدفع نقدًا (نحو ثلاثة
أيام). والمحاولة التي ينقضي عمرها تنتهي بحالة `expired`.

## الإجراءات التالية

ما دامت نية الدفع في `requires_action`، يوضح حقلها `next_action` ما على عميلك فعله. مع صفحة الدفع
المستضافة (hosted checkout) أو رابط الدفع لا تقرؤه أبدًا: صفحاتنا تتولى الأمر. أما مع صفحتك الخاصة:

* النوع `form_post`، للبطاقة: عنوان وحقول يرسلها متصفح عميلك للوصول إلى صفحة الدفع
  بالبطاقة.
* النوع `display_voucher`، للدفع نقدًا: الرمز `code`، والمبلغ `amount_to_pay` (مبلغك مضافًا إليه رسم
  طابع صغير يدفعه عميلك)، و`expires_at`، ورابط `slip_url` لوصل قابل للطباعة، و`hosted_voucher_url`
  وهو صفحة القسيمة لدينا.

## المبالغ والعملة

* كل مبلغ عدد صحيح **بالسنتيم**: `25000` تساوي 250.00 MAD. لا ترسل كسورًا عشرية أبدًا.
* قيمة `currency` هي دائمًا `mad`، بأحرف صغيرة.
* لا تقل الدفعة النقدية عن **100.00 MAD** (`10000`)، ولا الدفعة بالبطاقة عن 1.00 MAD (`100`).
  يُرفض أي مبلغ أصغر بالرمز `amount_too_small`، في وضع الاختبار كما في الوضع المباشر.

## إعادة التوجيه وإشعارات webhook: بأيهما تثق

يعود عميلك إلى `success_url` بعد الدفع، لكن هذه العودة لا تثبت شيئًا: قد يغلق علامة التبويب قبل
ذلك، والدفعة النقدية تُسدَّد بعد أيام لدى وكيل، وأي شخص يستطيع كتابة العنوان.

سلّم الطلبية بناءً على إحدى هاتين الإشارتين فقط:

1. **إشعار الـ webhook** `payment_intent.succeeded`، مع [توقيع تم التحقق منه](https://pay-docs.adpromax.com/ar/webhooks/signatures)؛
2. نية الدفع مقروءة من API بمفتاحك السري، وفيها `status: "succeeded"`.

استخدم العودة لشكر عميلك وعرض عبارة «نحن بصدد تأكيد دفعتك»؛ ثم دع الـ webhook يتكفل بالباقي.

## الاسترداد

يمكن استرداد الدفعة الناجحة **بالبطاقة**، كليًا أو جزئيًا، ما دام مجموع المبالغ المستردة لا يتجاوز
المبلغ المستلم. تكون عملية الاسترداد `pending`، ثم `succeeded` أو `failed` أو `canceled`.
أما الدفعة **النقدية** فلا يمكن استردادها عبر AdProMaxPay: سُلِّم المال نقدًا، ولا توجد بطاقة يُعاد
إليها. سوِّ الأمر مع عميلك مباشرة. انظر [المبالغ المستردة](https://pay-docs.adpromax.com/ar/payments/refunds).

## الأحداث التي تتلقاها

| الحدث                               | متى                                                                |
| ----------------------------------- | ------------------------------------------------------------------ |
| `payment_intent.requires_action`    | فُتحت صفحة بطاقة أو أُصدر رمز دفع نقدي.                            |
| `payment_intent.processing`         | دفع عميلك؛ والتأكيد في الطريق.                                     |
| `payment_intent.succeeded`          | تم تأكيد الدفعة. سلّم الطلبية.                                     |
| `payment_intent.payment_failed`     | فشلت محاولة: رفضها البنك، أو انتهت صلاحيتها، أو رفضتها شبكة الدفع. |
| `payment_intent.canceled`           | أُلغيت الدفعة.                                                     |
| `charge.succeeded`، `charge.failed` | نجحت محاولة أو فشلت.                                               |
| `review.opened`                     | لم يتطابق شيء؛ ولم يُضف أي مبلغ إلى رصيدك.                         |

القائمة الكاملة في [Webhooks](https://pay-docs.adpromax.com/ar/webhooks).