المدفوعات
كيف تعمل المدفوعات
نيات الدفع والمحاولات، والحالات التي تمر بها الدفعة، والإشارة التي تثق بها قبل تسليم الطلبية.
في هذه الصفحة
كل دفعة، بالبطاقة أو نقدًا، هي نية دفع (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. ثم ينظر فيها
أحد أعضاء فريقنا. وفي بيئة الاختبار، تتيح لك سيناريوهات الدفع النقدي
إحداث الحالتين.
المحاولات
تكون قيمة 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 بعد الدفع، لكن هذه العودة لا تثبت شيئًا: قد يغلق علامة التبويب قبل
ذلك، والدفعة النقدية تُسدَّد بعد أيام لدى وكيل، وأي شخص يستطيع كتابة العنوان.
سلّم الطلبية بناءً على إحدى هاتين الإشارتين فقط:
- إشعار الـ webhook
payment_intent.succeeded، مع توقيع تم التحقق منه؛ - نية الدفع مقروءة من API بمفتاحك السري، وفيها
status: "succeeded".
استخدم العودة لشكر عميلك وعرض عبارة «نحن بصدد تأكيد دفعتك»؛ ثم دع الـ webhook يتكفل بالباقي.
الاسترداد
يمكن استرداد الدفعة الناجحة بالبطاقة، كليًا أو جزئيًا، ما دام مجموع المبالغ المستردة لا يتجاوز
المبلغ المستلم. تكون عملية الاسترداد pending، ثم succeeded أو failed أو canceled.
أما الدفعة النقدية فلا يمكن استردادها عبر AdProMaxPay: سُلِّم المال نقدًا، ولا توجد بطاقة يُعاد
إليها. سوِّ الأمر مع عميلك مباشرة. انظر المبالغ المستردة.
الأحداث التي تتلقاها
| الحدث | متى |
|---|---|
payment_intent.requires_action | فُتحت صفحة بطاقة أو أُصدر رمز دفع نقدي. |
payment_intent.processing | دفع عميلك؛ والتأكيد في الطريق. |
payment_intent.succeeded | تم تأكيد الدفعة. سلّم الطلبية. |
payment_intent.payment_failed | فشلت محاولة: رفضها البنك، أو انتهت صلاحيتها، أو رفضتها شبكة الدفع. |
payment_intent.canceled | أُلغيت الدفعة. |
charge.succeeded، charge.failed | نجحت محاولة أو فشلت. |
review.opened | لم يتطابق شيء؛ ولم يُضف أي مبلغ إلى رصيدك. |
القائمة الكاملة في Webhooks.