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

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

ما هي Manual Retry؟

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

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

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

يمكن للمستخدمين الذين لديهم دور Owner أو Editor فقط إرسال محاولة يدوية.

Open the failed payment

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

Click Retry Payment Manually

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

Check the result

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

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

الأهلية

يرسل Dodo Payments محاولة يدوية فقط عندما تنجح جميع عمليات التحقق الواردة في هذا الجدول. يعرض عمود رمز السبب القيمة التي يعيدها 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`. وأي حالة أخرى، مثل `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. ويفشل هذا التحقق للاشتراك past_due الموجود في فترة سماح. وتستمر المحاولات التلقائية للحالات الأخرى غير النشطة. راجع انتقالات حالة الاشتراك.

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

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

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

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

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

المحاولات اليدوية مقابل التلقائية

يختلف مسارا إعادة المحاولة في الجوانب التالية:

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

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

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

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

لا يعيد 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. تعيد أمثلة SDK استخدام client من المثال السابق.

// `client` is the DodoPayments instance from the previous example.
const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

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

# `client` is the DodoPayments instance from the previous example.
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` عدم تسجيل أي نتيجة قبل إعادة الاستجابة. وفي كلتا الحالتين، تُبلغ payment webhooks بالنتيجة النهائية.
`retry_attempt`	ترتيب هذه المحاولة بين المحاولات اليدوية على الفاتورة، بدءًا من `1`.
`is_manual_retry`	دائمًا `true` على هذه النقطة.
`sends_used`، `sends_allowed`، `retry_available_at`	حالة حد إعادة المحاولة بعد هذا الإرسال. يمثل `retry_available_at` ساعة فترة التهدئة فقط. ويتم تعيينه حتى عند نجاح عملية التحصيل، وفي هذه الحالة تكون الفاتورة مدفوعة ولا تُتاح أي محاولة أخرى.

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

عندما لا يُسمح بإعادة المحاولة، يعيد POST إحدى حالات HTTP التالية:

حالة 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

ذات صلة