إعادة محاولة الدفع اليدوية

تُعيد Manual Retry محاولة دفع تجديد الاشتراك الفاشلة فور طلبك، من صفحة تفاصيل الدفع أو عبر API. وتخصم المبلغ من طريقة الدفع المحفوظة في الاشتراك، وتعمل بشكل مستقل عن جدول Payment Retries التلقائي.

ما هي Manual Retry؟

عند فشل دفعة التجديد، ينتقل الاشتراك إلى on_hold، وتعيد Payment Retries محاولة تحصيل المبلغ وفق جدول زمني متدرج. أحيانًا تعرف أن الدفع سينجح الآن: فقد يؤكد العميل أنه شحن رصيده، أو قد يكون فريق الدعم على اتصال به. تتيح لك Manual Retry إرسال محاولة واحدة فورًا بدلًا من الانتظار ساعات أو أيامًا حتى موعد المحاولة المجدولة التالية.

دفعات التجديد فقط: تنطبق Manual Retry على فواتير تجديد الاشتراكات عندما يكون الاشتراك في on_hold. ولا تكون الدفعات الأولى، والدفعات لمرة واحدة، والرسوم الناتجة عن تغيير الخطة، والرسوم عند الطلب مؤهلة.
لا يتطلب إجراءً من العميل: تُرسل عملية الخصم إلى طريقة الدفع المحفوظة مسبقًا في الاشتراك.
مستقلة عن الإعادات التلقائية: لا تستهلك إعادة المحاولة اليدوية محاولةً من الجدول التلقائي، ولا تغيّر موعد إعادة المحاولة المجدولة التالية، وتعمل حتى عند إيقاف Payment Retries.
تعيد محاولة الفاتورة، وليس الدفع: الدفع الفاشل هو نقطة البداية فقط. يبحث Dodo Payments عن فاتورة التجديد المفتوحة المرتبطة به ويحصّل ذلك الدين، لذلك لا يهم أي دفعة فاشلة في الفاتورة تعيد المحاولة منها.

إعادة المحاولة من لوحة التحكم

Open the failed payment

انتقل إلى المعاملات ← الدفعات وانقر على دفعة التجديد الفاشلة لفتح صفحة تفاصيل المعاملة.

Click Retry Payment Manually

انقر على Retry Payment Manually في الزاوية العلوية اليسرى. لا يتوفر الزر إلا عندما تكون الدفعة مؤهلة.

Check the result

يُنشأ دفع جديد للمحاولة ويظهر في سجل النشاط. إذا نجحت عملية الخصم، يعود الاشتراك إلى active ويتقدم تاريخ الفوترة التالي كالمعتاد. وإذا لم يكن معالج الدفع قد سوّى عملية الخصم بعد، فستظهر الدفعة قيد التنفيذ إلى أن تُبلغ webhook‏ payment.succeeded أو payment.failed بالنتيجة.

صفحة تفاصيل المعاملة لدفعة فاشلة تعرض رمز الخطأ والرسالة وسجل النشاط وزر إعادة محاولة الدفع يدويًا — Retry Payment Manually on the transaction details page of a failed renewal

الأهلية

لا تُرسل إعادة المحاولة اليدوية إلا عند اجتياز جميع الفحوصات أدناه. يعرض عمود رمز السبب ما يعيده API: في reason على GET /payments/{payment_id}/retry، وكخطأ code على POST /payments/{payment_id}/retry.

الفحص	المتطلب	رمز السبب
نوع الدفع	دفعة تجديد لاشتراك تكون فاتورتها لا تزال مفتوحة. لا يمكن إعادة محاولة الدفعات التي لا تحتوي على فاتورة، والدفعات الأولى، والدفعات لمرة واحدة، والرسوم الناتجة عن تغيير الخطة، والرسوم عند الطلب.	`PAYMENT_NOT_RETRYABLE`
حالة الاشتراك	`on_hold`	`SUBSCRIPTION_INACTIVE`
الإلغاء المجدول	لم تتم جدولة إلغاء الاشتراك في تاريخ الفوترة التالي.	`CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`
طريقة الدفع المحفوظة	يحتوي الاشتراك على طريقة دفع محفوظة يمكن الخصم منها.	`SUBSCRIPTION_HAS_NO_PAYMENT_METHOD`
آخر فشل	أحدث فشل هو رفض مؤقت. لا يمكن إعادة محاولة الرفض النهائي أو الفشل الذي لا يتضمن رمز خطأ مصنفًا.	`MANUAL_RETRY_HARD_DECLINE`
لا توجد عملية قيد التنفيذ	لا توجد دفعة في الفاتورة في حالة `processing` أو بلا حالة مسجلة حتى الآن. هذه محاولة، يدوية أو تلقائية، أُرسلت للتو ولم تُرجع نتيجة بعد. انتظر نتيجتها أولًا.	`MANUAL_RETRY_IN_FLIGHT`
فشل أحدث دفعة	تحمل أحدث دفعة في الفاتورة حالة `failed`. تؤدي أحدث دفعة في أي حالة أخرى غير `failed`، مثل `requires_customer_action` أو `requires_payment_method` أو `cancelled`، إلى منع إعادة المحاولة حتى عند عدم وجود عملية قيد التنفيذ.	`PREVIOUS_PAYMENT_PENDING`
لم تُدفع بعد	لم تنجح أي دفعة في الفاتورة.	`MANUAL_RETRY_ALREADY_PAID`
حد إعادة المحاولة	أُرسلت أقل من 3 إعادات محاولة يدوية على الفاتورة، وانتهت فترة التهدئة. راجع حدود إعادة المحاولة.	`MANUAL_RETRY_LIMIT_REACHED`
العميل	العميل ليس ضمن قائمة الحظر الخاصة بك.	`PAYMENT_NOT_RETRYABLE`
موصل الدفع	بالنسبة إلى اشتراكات BYOP، يكون الموصل مفعّلًا.	`BYOP_CONNECTOR_DISABLED`
الوضع المباشر	في الوضع المباشر، تكون الدفعات المباشرة مفعّلة لنشاطك التجاري.	`MERCHANT_NOT_LIVE`

Manual Retry أضيق نطاقًا من الإعادات التلقائية في نقطة واحدة: فهي تتطلب أن يكون الاشتراك في on_hold. تستمر الإعادات التلقائية في الحالات الأخرى غير النشطة؛ راجع انتقالات حالة الاشتراك.

لا يمكن أن تنجح إعادة محاولة الرفض النهائي باستخدام البطاقة نفسها، كما أن الرفض المتكرر يضر بمعدل التفويض لديك. عندما يكون السبب MANUAL_RETRY_HARD_DECLINE، اطلب من العميل تحديث طريقة الدفع بدلًا من ذلك. تتولى Subscription Dunning هذا الأمر تلقائيًا.

حدود إعادة المحاولة

تسمح كل فاتورة تجديد بـ 3 إعادات محاولة يدوية، مع فترة تهدئة بينها:

إعادة المحاولة اليدوية	متاحة
1	بمجرد أن تصبح الدفعة مؤهلة
2	بعد ساعة واحدة من الأولى
3	بعد 3 ساعات من الثانية

تنطبق الحدود في كل من وضع الاختبار والوضع المباشر. عند رفض إعادة المحاولة لهذا السبب، يعيد API القيمة MANUAL_RETRY_LIMIT_REACHED ‏(HTTP 429). ولا يحتوي نص الخطأ إلا على code وmessage. لمعرفة موعد فتح إعادة المحاولة التالية، تحقق من حالة إعادة المحاولة واقرأ retry_available_at. وتكون null بعد استنفاد الإعادات الثلاث جميعها. لا تُحتسب الإعادات التلقائية ضمن هذا الحد، ولا تُحتسب الإعادات اليدوية ضمن محاولات الجدول التلقائي البالغ عددها 8.

الإعادات اليدوية مقابل التلقائية

	Manual Retry	Payment Retries
المشغّل	أنت، من لوحة التحكم أو API	Dodo Payments، وفق جدول زمني متدرج
التوقيت	فورًا	بعد 12 ساعة من الفشل، ثم في أوقات لاحقة تدريجيًا
المحاولات	3 لكل فاتورة، مع فترة تهدئة مدتها ساعة واحدة ثم 3 ساعات	حتى 8 لكل فاتورة، ضمن فترة الاسترداد
يتطلب تفعيل Payment Retries	لا	نعم
التأثير في الآخر	لا يوجد. لا تؤدي الإعادة اليدوية الفاشلة إلى جدولة محاولة تلقائية أو تغيير موعدها.	لا يوجد. تستمر السلسلة التلقائية بغض النظر عن الإعادات اليدوية.
التحليلات	تُحتسب ضمن مقاييس إعادات محاولة الدفع في علامة تبويب الاسترداد	تُحتسب ضمن المقاييس نفسها

إعادة المحاولة عبر API

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

التحقق مما إذا كان يمكن إعادة محاولة الدفع

لا يفشل GET /payments/{payment_id}/retry أبدًا عند التعامل مع دفعة غير مؤهلة. بل يعيد can_retry: false مع رمز reason، حتى تتمكن لوحة التحكم أو أدوات الدعم لديك من عرض الحالة نفسها التي تعرضها لوحة تحكم Dodo Payments. ويتطلب ذلك دور Viewer.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

const state = await client.payments.retrieveRetryState('pay_0NmDtkE0iRvmeTcT6t0ol');

if (state.can_retry) {
  console.log(`Retry available. ${state.sends_used}/${state.sends_allowed} used.`);
} else {
  console.log(`Cannot retry: ${state.reason}. Next window: ${state.retry_available_at}`);
}

import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

state = client.payments.retrieve_retry_state("pay_0NmDtkE0iRvmeTcT6t0ol")

if state.can_retry:
    print(f"Retry available. {state.sends_used}/{state.sends_allowed} used.")
else:
    print(f"Cannot retry: {state.reason}. Next window: {state.retry_available_at}")

curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "can_retry": false,
  "reason": "MANUAL_RETRY_LIMIT_REACHED",
  "sends_used": 1,
  "sends_allowed": 3,
  "retry_available_at": "2026-08-26T16:51:00Z"
}

الحقل	الوصف
`can_retry`	`true` عندما تكون إعادة المحاولة سترسل الآن.
`reason`	الرمز الذي ستفشل به إعادة المحاولة. `null` عندما تكون `can_retry` هي `true`.
`sends_used`	الإعادات اليدوية المرسلة مسبقًا على هذه الفاتورة.
`sends_allowed`	دائمًا `3`.
`retry_available_at`	موعد فتح إعادة المحاولة اليدوية التالية. `null` عند عدم بقاء أي إعادة محاولة، أو عندما لا يكون سبب الرفض متعلقًا بفترة التهدئة.

إرسال إعادة محاولة يدوية

ينشئ POST /payments/{payment_id}/retry دفعة جديدة ويخصم المبلغ من طريقة الدفع المحفوظة. ويتطلب ذلك دور Editor.

const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

console.log(retry.payment_id, retry.status);

retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")

print(retry.payment_id, retry.status)

curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
  "invoice_id": "inv_9Kp2mQ7vRt4LxYw3",
  "status": "processing",
  "retry_attempt": 1,
  "is_manual_retry": true,
  "sends_used": 1,
  "sends_allowed": 3,
  "retry_available_at": "2026-08-26T16:51:00Z"
}

الحقل	الوصف
`payment_id`	الدفعة الجديدة التي أُنشئت لهذه المحاولة.
`invoice_id`	فاتورة التجديد التي جرى تحصيلها.
`status`	نتيجة عملية الخصم. تعني `processing` أن المعالج لم يُسوِّ العملية بعد. وتعني `null` عدم تسجيل نتيجة قبل إرجاع الاستجابة. في كلتا الحالتين، تُبلغ webhooks الخاصة بالدفع بالنتيجة النهائية.
`retry_attempt`	ترتيب هذه المحاولة بين الإعادات اليدوية على الفاتورة، بدءًا من `1`.
`is_manual_retry`	دائمًا `true` على هذه النقطة النهائية.
`sends_used`، `sends_allowed`، `retry_available_at`	حالة حد إعادة المحاولة بعد هذا الإرسال. لا يشير `retry_available_at` إلا إلى مؤقت فترة التهدئة. ويتم تعيينه حتى عند نجاح عملية الخصم، وفي هذه الحالة تكون الفاتورة مدفوعة ولا تُفتح أي إعادة محاولة أخرى.

استجابات الخطأ

حالة HTTP	الرموز	الإجراء
`404`	`NOT_FOUND`	لا تنتمي الدفعة إلى نشاطك التجاري.
`409`	`MANUAL_RETRY_IN_FLIGHT`، `PREVIOUS_PAYMENT_PENDING`، `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`	مؤقت، أو يجب تغيير أمر آخر أولًا. انتظر حتى تصل الدفعة قيد التنفيذ أو المعلّقة إلى حالة نهائية، أو أزل الإلغاء المجدول.
`422`	`PAYMENT_NOT_RETRYABLE`، `SUBSCRIPTION_INACTIVE`، `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD`، `MANUAL_RETRY_HARD_DECLINE`، `MANUAL_RETRY_ALREADY_PAID`، `BYOP_CONNECTOR_DISABLED`، `MERCHANT_NOT_LIVE`	لا يمكن إعادة محاولة هذه الدفعة. لا تكرر الاستدعاء.
`429`	`MANUAL_RETRY_LIMIT_REACHED`	تحقق من حالة إعادة المحاولة وانتظر حتى `retry_available_at`، أو توقف بعد استنفاد الإعادات الثلاث جميعها.

يُوضَّح كل رمز في مرجع رموز الخطأ.

Webhooks

تنشئ إعادة المحاولة اليدوية دفعة عادية، لذلك تُطلق webhooks نفسها كما هو الحال مع أي محاولة تجديد:

الحدث	يُطلَق عند
`payment.succeeded`	تحصيل قيمة إعادة المحاولة. ويتبعها `subscription.active` عند إعادة تفعيل الاشتراك.
`payment.failed`	رفض إعادة المحاولة. يبقى الاشتراك في `on_hold`، ولا تُجدول إعادة محاولة تلقائية نتيجة فشل يدوي.
`payment.processing`	قبول المعالج لعملية الخصم دون تسويتها بعد.

في كائن الدفع ضمن هذه الأحداث، تكون retry_attempt بقيمة 1 أو أعلى، وتُعيّن subscription_id، تمامًا كما في الإعادة التلقائية. احتفظ بقيمة payment_id من استجابة إعادة المحاولة إذا احتجت إلى تمييز المحاولة اليدوية عن المجدولة.

Payment Webhook Payloads

مخططات الحمولة الكاملة لأحداث الدفع.

Subscription Payment Retries

الجدول الزمني التلقائي المتدرج الذي يعمل بالتوازي مع الإعادات اليدوية.

Subscription Dunning

أرسل بريدًا إلكترونيًا إلى العميل لتحديث طريقة الدفع بعد الرفض النهائي.

Handle Payment Failures

اقرأ رموز الرفض وحدد متى تستحق إعادة المحاولة.

Error Codes

كل رمز MANUAL_RETRY_*، والمشغّل الخاص به، ورسالته.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

إعادة محاولة الدفع اليدوية

ما هي Manual Retry؟

إعادة المحاولة من لوحة التحكم

الأهلية

حدود إعادة المحاولة

الإعادات اليدوية مقابل التلقائية

إعادة المحاولة عبر API

التحقق مما إذا كان يمكن إعادة محاولة الدفع

إرسال إعادة محاولة يدوية

استجابات الخطأ

Webhooks

Payment Webhook Payloads

ذات صلة

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

​ما هي Manual Retry؟

​إعادة المحاولة من لوحة التحكم

​الأهلية

​حدود إعادة المحاولة

​الإعادات اليدوية مقابل التلقائية

​إعادة المحاولة عبر API

​التحقق مما إذا كان يمكن إعادة محاولة الدفع

​إرسال إعادة محاولة يدوية

​استجابات الخطأ

​Webhooks

Payment Webhook Payloads

​ذات صلة

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

ما هي Manual Retry؟

إعادة المحاولة من لوحة التحكم

الأهلية

حدود إعادة المحاولة

الإعادات اليدوية مقابل التلقائية

إعادة المحاولة عبر API

التحقق مما إذا كان يمكن إعادة محاولة الدفع

إرسال إعادة محاولة يدوية

استجابات الخطأ

Webhooks

ذات صلة