> ## 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.
# Manueller Wiederholungsversuch für Zahlungen
> Fordern Sie die Zahlung für eine fehlgeschlagene Abonnementverlängerung über das Dashboard oder die API erneut an, anstatt auf den nächsten automatischen Wiederholungsversuch zu warten.
Mit dem manuellen Wiederholungsversuch wird eine fehlgeschlagene **Verlängerungszahlung** sofort erneut versucht, sobald Sie dies anfordern – über die Detailseite der Zahlung oder die API. Dabei wird die für das Abonnement gespeicherte Zahlungsmethode belastet. Der Vorgang läuft unabhängig vom Zeitplan für automatische [Zahlungswiederholungen](/features/recovery/payment-retries).
## Was ist ein manueller Wiederholungsversuch?
Wenn eine Verlängerungszahlung fehlschlägt, wechselt das Abonnement zu `on_hold` und [Zahlungswiederholungen](/features/recovery/payment-retries) versuchen, die Zahlung nach einem Back-off-Zeitplan erneut einzuziehen. Manchmal wissen Sie, dass die Zahlung jetzt durchgeführt werden kann: Ein Kunde hat beispielsweise bestätigt, dass er sein Konto aufgeladen hat, oder Ihr Support-Team telefoniert gerade mit ihm. Mit einem manuellen Wiederholungsversuch können Sie sofort einen Versuch senden, statt Stunden oder Tage auf den nächsten geplanten Versuch zu warten.
* **Nur Verlängerungszahlungen**: Der manuelle Wiederholungsversuch gilt für Verlängerungsrechnungen von Abonnements, während das Abonnement den Status `on_hold` hat. Erstzahlungen, einmalige Zahlungen, Gebühren für Planänderungen und anlassbezogene Gebühren sind nicht berechtigt.
* **Keine Aktion des Kunden erforderlich**: Die gespeicherte Zahlungsmethode des Abonnements wird belastet.
* **Unabhängig von automatischen Wiederholungsversuchen**: Ein manueller Wiederholungsversuch verbraucht keinen Versuch aus dem automatischen Zeitplan, verschiebt den nächsten geplanten Versuch nicht und funktioniert auch dann, wenn Zahlungswiederholungen deaktiviert sind.
* **Die Rechnung, nicht die Zahlung, wird wiederholt**: Eine fehlgeschlagene Zahlung ist nur der Ausgangspunkt. Dodo Payments sucht die dahinterliegende offene Verlängerungsrechnung und begleicht diese Schuld. Daher spielt es keine Rolle, von welcher fehlgeschlagenen Zahlung der Rechnung aus Sie den Versuch wiederholen.
## Wiederholung über das Dashboard
Gehen Sie zu **Transaktionen → Zahlungen** und klicken Sie auf die fehlgeschlagene Verlängerungszahlung, um die Seite **Transaktionsdetails** zu öffnen.
Klicken Sie oben rechts auf **Zahlung manuell wiederholen**. Die Schaltfläche ist nur verfügbar, solange die Zahlung [berechtigt](#eligibility) ist.
Für den Versuch wird eine neue Zahlung erstellt und im **Aktivitätsprotokoll** angezeigt. Wenn die Belastung erfolgreich ist, erhält das Abonnement wieder den Status `active` und das nächste Abrechnungsdatum wird wie gewohnt weitergeschoben. Wenn der Zahlungsprozessor die Belastung noch nicht abgeschlossen hat, wird die Zahlung als in Bearbeitung angezeigt, bis der Webhook `payment.succeeded` oder `payment.failed` das Ergebnis meldet.
## Berechtigung
Ein manueller Wiederholungsversuch wird nur gesendet, wenn alle folgenden Prüfungen erfolgreich sind. Die Spalte **Reason code** enthält den von der API zurückgegebenen Wert: in `reason` bei `GET /payments/{payment_id}/retry` und als Fehler `code` bei `POST /payments/{payment_id}/retry`.
| Prüfung | Voraussetzung | Reason code |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| Zahlungstyp | Eine **Verlängerungszahlung** eines Abonnements, deren Rechnung noch offen ist. Zahlungen ohne Rechnung, Erstzahlungen, einmalige Zahlungen, Gebühren für Planänderungen und anlassbezogene Gebühren können nicht wiederholt werden. | `PAYMENT_NOT_RETRYABLE` |
| Abonnementstatus | `on_hold` | `SUBSCRIPTION_INACTIVE` |
| Geplante Kündigung | Das Abonnement ist nicht so eingestellt, dass es zum nächsten Abrechnungsdatum gekündigt wird. | `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` |
| Gespeicherte Zahlungsmethode | Für das Abonnement ist eine belastbare Zahlungsmethode gespeichert. | `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD` |
| Letzter Fehler | Der letzte Fehler ist ein **Soft Decline**. Ein Hard Decline oder ein Fehler ohne klassifizierten Fehlercode kann nicht wiederholt werden. | `MANUAL_RETRY_HARD_DECLINE` |
| Nichts in Bearbeitung | Keine Zahlung der Rechnung hat den Status `processing` oder keinen erfassten Status. Dies kann ein gerade gesendeter manueller oder automatischer Versuch sein, der noch nicht zurückgemeldet wurde. Warten Sie zunächst auf das Ergebnis. | `MANUAL_RETRY_IN_FLIGHT` |
| Neueste Zahlung fehlgeschlagen | Die neueste Zahlung der Rechnung hat den Status `failed`. Eine neueste Zahlung in einem anderen Status als `failed`, beispielsweise `requires_customer_action`, `requires_payment_method` oder `cancelled`, blockiert die Wiederholung, selbst wenn nichts in Bearbeitung ist. | `PREVIOUS_PAYMENT_PENDING` |
| Noch nicht bezahlt | Keine Zahlung der Rechnung war erfolgreich. | `MANUAL_RETRY_ALREADY_PAID` |
| Wiederholungslimit | Weniger als 3 manuelle Wiederholungsversuche wurden für die Rechnung gesendet und die Abkühlzeit ist abgelaufen. Siehe [Wiederholungslimits](#retry-limits). | `MANUAL_RETRY_LIMIT_REACHED` |
| Kunde | Der Kunde steht nicht auf Ihrer [Sperrliste](/features/customer-blocklist). | `PAYMENT_NOT_RETRYABLE` |
| Zahlungsconnector | Bei Abonnements mit [BYOP](/features/byop) ist der Connector aktiviert. | `BYOP_CONNECTOR_DISABLED` |
| Live-Modus | Im Live-Modus sind Live-Zahlungen für Ihr Unternehmen aktiviert. | `MERCHANT_NOT_LIVE` |
Der manuelle Wiederholungsversuch ist in einem Punkt eingeschränkter als automatische Wiederholungsversuche: Das Abonnement muss den Status `on_hold` haben. Automatische Wiederholungsversuche laufen auch bei anderen nicht aktiven Status weiter. Siehe [Übergänge von Abonnementstatus](/features/recovery/payment-retries#subscription-status-transitions).
Eine Wiederholung eines Hard Decline mit derselben Karte kann nicht erfolgreich sein, und wiederholte Ablehnungen beeinträchtigen Ihre Autorisierungsrate. Wenn der Grund `MANUAL_RETRY_HARD_DECLINE` lautet, bitten Sie den Kunden stattdessen, seine Zahlungsmethode zu aktualisieren. [Subscription Dunning](/features/recovery/subscription-dunning) erledigt dies automatisch.
## Wiederholungslimits
Für jede Verlängerungsrechnung sind **3** manuelle Wiederholungsversuche mit einer Abkühlzeit dazwischen zulässig:
| Manueller Wiederholungsversuch | Verfügbar |
| ------------------------------ | --------------------------------- |
| 1 | Sobald die Zahlung berechtigt ist |
| 2 | 1 Stunde nach dem ersten |
| 3 | 3 Stunden nach dem zweiten |
Die Limits gelten sowohl im Testmodus als auch im Live-Modus. Wenn ein Wiederholungsversuch aus diesem Grund abgelehnt wird, gibt die API `MANUAL_RETRY_LIMIT_REACHED` (HTTP `429`) zurück. Der Fehler-Body enthält nur `code` und `message`. Um zu erfahren, wann der nächste Versuch möglich ist, [prüfen Sie den Status der Wiederholung](#check-whether-a-payment-can-be-retried) und lesen Sie `retry_available_at`. Der Wert ist `null`, sobald alle drei Versuche aufgebraucht sind.
Automatische Wiederholungsversuche zählen nicht zu diesem Limit, und manuelle Wiederholungsversuche zählen nicht zu den 8 Versuchen des automatischen Zeitplans.
## Manuelle und automatische Wiederholungsversuche
| | Manueller Wiederholungsversuch | Zahlungswiederholungen |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Auslöser** | Sie über das Dashboard oder die API | Dodo Payments nach einem Back-off-Zeitplan |
| **Zeitpunkt** | Sofort | 12 Stunden nach dem Fehler, danach zunehmend später |
| **Versuche** | 3 pro Rechnung, mit einer Abkühlzeit von 1 Stunde und danach 3 Stunden | Bis zu 8 pro Rechnung innerhalb Ihres Wiederherstellungszeitraums |
| **Zahlungswiederholungen müssen aktiviert sein** | Nein | Ja |
| **Auswirkung auf den jeweils anderen Mechanismus** | Keine. Ein manueller Fehler plant keinen automatischen Versuch und verschiebt ihn nicht. | Keine. Die automatische Kette läuft unabhängig von manuellen Versuchen weiter. |
| **Analysen** | Wird in den Metriken für **Zahlungswiederholungen** im Tab „Wiederherstellung“ gezählt | Wird in denselben Metriken gezählt |
## Wiederholung über die API
Prüfen Sie zuerst die Berechtigung und senden Sie anschließend den Wiederholungsversuch. Beide Endpunkte benötigen die ID einer fehlgeschlagenen Zahlung.
### Prüfen, ob eine Zahlung wiederholt werden kann
`GET /payments/{payment_id}/retry` schlägt bei einer nicht berechtigten Zahlung nie fehl. Stattdessen wird `can_retry: false` mit dem Code `reason` zurückgegeben. So können Ihr Dashboard oder Ihre Support-Tools denselben Status anzeigen wie das Dashboard von Dodo Payments. Die Rolle **Viewer** ist erforderlich.
```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"
```
```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"
}
```
| Feld | Beschreibung |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `can_retry` | `true`, wenn jetzt ein Wiederholungsversuch gesendet würde. |
| `reason` | Der Code, mit dem der Wiederholungsversuch fehlschlagen würde. `null`, wenn `can_retry` den Wert `true` hat. |
| `sends_used` | Bereits für diese Rechnung gesendete manuelle Wiederholungsversuche. |
| `sends_allowed` | Immer `3`. |
| `retry_available_at` | Zeitpunkt, ab dem der nächste manuelle Wiederholungsversuch möglich ist. `null`, wenn kein Versuch mehr übrig ist oder die Ablehnung nichts mit der Abkühlzeit zu tun hat. |
### Manuellen Wiederholungsversuch senden
`POST /payments/{payment_id}/retry` erstellt eine neue Zahlung und belastet die gespeicherte Zahlungsmethode. Die Rolle **Editor** ist erforderlich.
```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"
```
```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"
}
```
| Feld | Beschreibung |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_id` | Die für diesen Versuch erstellte neue Zahlung. |
| `invoice_id` | Die belastete Verlängerungsrechnung. |
| `status` | Ergebnis der Belastung. `processing` bedeutet, dass der Zahlungsprozessor die Zahlung noch nicht abgeschlossen hat. `null` bedeutet, dass vor der Rückgabe der Antwort kein Ergebnis erfasst wurde. In beiden Fällen melden die Zahlungs-Webhooks das endgültige Ergebnis. |
| `retry_attempt` | Position dieses Versuchs unter den manuellen Wiederholungsversuchen der Rechnung, beginnend bei `1`. |
| `is_manual_retry` | Bei diesem Endpunkt immer `true`. |
| `sends_used`, `sends_allowed`, `retry_available_at` | Status des Wiederholungslimits nach diesem Versand. `retry_available_at` betrifft nur die Abkühlzeit. Der Wert wird auch dann gesetzt, wenn diese Belastung erfolgreich ist; in diesem Fall ist die Rechnung bezahlt und es wird kein weiterer Versuch möglich. |
### Fehlerantworten
| HTTP status | Codes | Maßnahme |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404` | `NOT_FOUND` | Die Zahlung gehört nicht zu Ihrem Unternehmen. |
| `409` | `MANUAL_RETRY_IN_FLIGHT`, `PREVIOUS_PAYMENT_PENDING`, `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` | Vorübergehender Fehler oder zunächst muss etwas anderes geändert werden. Warten Sie, bis die Zahlung in Bearbeitung oder ausstehende Zahlung einen endgültigen Status erreicht, oder entfernen Sie die geplante Kündigung. |
| `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` | Diese Zahlung kann nicht wiederholt werden. Wiederholen Sie den Aufruf nicht. |
| `429` | `MANUAL_RETRY_LIMIT_REACHED` | [Prüfen Sie den Status der Wiederholung](#check-whether-a-payment-can-be-retried) und warten Sie, bis `retry_available_at` erreicht ist, oder beenden Sie den Vorgang, sobald alle drei Versuche aufgebraucht sind. |
Jeder Code wird in der Referenz [Fehlercodes](/api-reference/error-codes) beschrieben.
## Webhooks
Ein manueller Wiederholungsversuch erstellt eine normale Zahlung. Daher werden dieselben Webhooks ausgelöst wie bei jedem Verlängerungsversuch:
| Ereignis | Wird ausgelöst, wenn |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` | die Wiederholung belastet wurde. `subscription.active` folgt, sobald das Abonnement reaktiviert wird. |
| `payment.failed` | die Wiederholung abgelehnt wurde. Das Abonnement bleibt im Status `on_hold`, und aufgrund eines manuellen Fehlers wird kein automatischer Wiederholungsversuch geplant. |
| `payment.processing` | der Prozessor die Belastung akzeptiert, aber noch nicht abgeschlossen hat. |
Im Zahlungsobjekt dieser Ereignisse ist `retry_attempt` `1` oder höher, und `subscription_id` ist gesetzt – genau wie bei einem automatischen Wiederholungsversuch. Bewahren Sie `payment_id` aus der Antwort des Wiederholungsversuchs auf, wenn Sie einen manuellen von einem geplanten Versuch unterscheiden müssen.
Vollständige Payload-Schemas für Zahlungsereignisse.
## Verwandte Themen
Der automatische Back-off-Zeitplan, der parallel zu manuellen Wiederholungsversuchen ausgeführt wird.
Senden Sie dem Kunden eine E-Mail, damit er seine Zahlungsmethode nach einem Hard Decline aktualisiert.
Lesen Sie Ablehnungscodes und entscheiden Sie, wann sich ein Wiederholungsversuch lohnt.
Jeder `MANUAL_RETRY_*`-Code, sein Auslöser und seine Meldung.