> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> أعد محاولة دفع تجديد الاشتراك الفاشل عند الطلب من لوحة التحكم أو عبر API بدلًا من الانتظار حتى موعد إعادة المحاولة التلقائية التالية.

<Info>
  تُعيد Manual Retry محاولة دفع **تجديد** الاشتراك الفاشلة فور طلبك، من صفحة تفاصيل الدفع أو عبر API. وتخصم المبلغ من طريقة الدفع المحفوظة في الاشتراك، وتعمل بشكل مستقل عن جدول [Payment Retries](/features/recovery/payment-retries) التلقائي.
</Info>

## ما هي Manual Retry؟

عند فشل دفعة التجديد، ينتقل الاشتراك إلى `on_hold`، وتعيد [Payment Retries](/features/recovery/payment-retries) محاولة تحصيل المبلغ وفق جدول زمني متدرج. أحيانًا تعرف أن الدفع سينجح الآن: فقد يؤكد العميل أنه شحن رصيده، أو قد يكون فريق الدعم على اتصال به. تتيح لك Manual Retry إرسال محاولة واحدة فورًا بدلًا من الانتظار ساعات أو أيامًا حتى موعد المحاولة المجدولة التالية.

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

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

<Steps>
  <Step title="Open the failed payment">
    انتقل إلى **المعاملات ← الدفعات** وانقر على دفعة التجديد الفاشلة لفتح صفحة **تفاصيل المعاملة**.
  </Step>

  <Step title="Click Retry Payment Manually">
    انقر على **Retry Payment Manually** في الزاوية العلوية اليسرى. لا يتوفر الزر إلا عندما تكون الدفعة [مؤهلة](#eligibility).
  </Step>

  <Step title="Check the result">
    يُنشأ دفع جديد للمحاولة ويظهر في **سجل النشاط**. إذا نجحت عملية الخصم، يعود الاشتراك إلى `active` ويتقدم تاريخ الفوترة التالي كالمعتاد. وإذا لم يكن معالج الدفع قد سوّى عملية الخصم بعد، فستظهر الدفعة قيد التنفيذ إلى أن تُبلغ webhook‏ `payment.succeeded` أو `payment.failed` بالنتيجة.
  </Step>
</Steps>

<Frame caption="Retry Payment Manually on the transaction details page of a failed renewal">
  <img src="https://mintcdn.com/dodopayments/0duTS18kYi2NwQ3m/images/recovery/manual-retry-transaction-details.png?fit=max&auto=format&n=0duTS18kYi2NwQ3m&q=85&s=5537fa5eff17cbe91a53599f887a26e7" alt="صفحة تفاصيل المعاملة لدفعة فاشلة تعرض رمز الخطأ والرسالة وسجل النشاط وزر إعادة محاولة الدفع يدويًا" style={{ maxHeight: '500px', width: 'auto' }} width="1285" height="698" data-path="images/recovery/manual-retry-transaction-details.png" />
</Frame>

## الأهلية

لا تُرسل إعادة المحاولة اليدوية إلا عند اجتياز جميع الفحوصات أدناه. يعرض عمود **رمز السبب** ما يعيده 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 إعادات محاولة يدوية على الفاتورة، وانتهت فترة التهدئة. راجع [حدود إعادة المحاولة](#retry-limits).                                                                                                             | `MANUAL_RETRY_LIMIT_REACHED`                    |
| العميل                    | العميل ليس ضمن [قائمة الحظر](/features/customer-blocklist) الخاصة بك.                                                                                                                                                         | `PAYMENT_NOT_RETRYABLE`                         |
| موصل الدفع                | بالنسبة إلى اشتراكات [BYOP](/features/byop)، يكون الموصل مفعّلًا.                                                                                                                                                             | `BYOP_CONNECTOR_DISABLED`                       |
| الوضع المباشر             | في الوضع المباشر، تكون الدفعات المباشرة مفعّلة لنشاطك التجاري.                                                                                                                                                                | `MERCHANT_NOT_LIVE`                             |

<Note>
  Manual Retry أضيق نطاقًا من الإعادات التلقائية في نقطة واحدة: فهي تتطلب أن يكون الاشتراك في `on_hold`. تستمر الإعادات التلقائية في الحالات الأخرى غير النشطة؛ راجع [انتقالات حالة الاشتراك](/features/recovery/payment-retries#subscription-status-transitions).
</Note>

<Warning>
  لا يمكن أن تنجح إعادة محاولة الرفض النهائي باستخدام البطاقة نفسها، كما أن الرفض المتكرر يضر بمعدل التفويض لديك. عندما يكون السبب `MANUAL_RETRY_HARD_DECLINE`، اطلب من العميل تحديث طريقة الدفع بدلًا من ذلك. تتولى [Subscription Dunning](/features/recovery/subscription-dunning) هذا الأمر تلقائيًا.
</Warning>

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

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

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

تنطبق الحدود في كل من وضع الاختبار والوضع المباشر. عند رفض إعادة المحاولة لهذا السبب، يعيد API القيمة `MANUAL_RETRY_LIMIT_REACHED` ‏(HTTP `429`). ولا يحتوي نص الخطأ إلا على `code` و`message`. لمعرفة موعد فتح إعادة المحاولة التالية، [تحقق من حالة إعادة المحاولة](#check-whether-a-payment-can-be-retried) واقرأ `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**.

<CodeGroup>
  ```typescript Node.js theme={null}
  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}`);
  }
  ```

  ```python Python theme={null}
  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}")
  ```

  ```bash cURL theme={null}
  curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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**.

<CodeGroup>
  ```typescript Node.js theme={null}
  const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

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

  ```python Python theme={null}
  retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")

  print(retry.payment_id, retry.status)
  ```

  ```bash cURL theme={null}
  curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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`                                                                                                                                                                     | [تحقق من حالة إعادة المحاولة](#check-whether-a-payment-can-be-retried) وانتظر حتى `retry_available_at`، أو توقف بعد استنفاد الإعادات الثلاث جميعها. |

يُوضَّح كل رمز في مرجع [رموز الخطأ](/api-reference/error-codes).

## Webhooks

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

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

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

<Card title="Payment Webhook Payloads" icon="webhook" href="/developer-resources/webhooks/intents/payment">
  مخططات الحمولة الكاملة لأحداث الدفع.
</Card>

## ذات صلة

<CardGroup cols={2}>
  <Card title="Subscription Payment Retries" icon="arrow-rotate-right" href="/features/recovery/payment-retries">
    الجدول الزمني التلقائي المتدرج الذي يعمل بالتوازي مع الإعادات اليدوية.
  </Card>

  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    أرسل بريدًا إلكترونيًا إلى العميل لتحديث طريقة الدفع بعد الرفض النهائي.
  </Card>

  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    اقرأ رموز الرفض وحدد متى تستحق إعادة المحاولة.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    كل رمز `MANUAL_RETRY_*`، والمشغّل الخاص به، ورسالته.
  </Card>
</CardGroup>