> ## 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 から、失敗したサブスクリプション更新決済をオンデマンドで再試行します。 Manual Retry は、決済の詳細ページまたは API からリクエストすると、失敗したサブスクリプションの**更新**決済を直ちに再試行します。サブスクリプションに保存されている決済手段に請求し、自動の [Payment Retries](/features/recovery/payment-retries) スケジュールとは独立して実行されます。 ## Manual Retry とは？ 更新決済に失敗すると、サブスクリプションは `on_hold` に移行し、[Payment Retries](/features/recovery/payment-retries) がバックオフスケジュールに従って請求を再試行します。顧客がアカウントへのチャージを確認した場合や、サポートチームが顧客と通話中の場合など、すぐに決済が成功すると分かっていることもあります。Manual Retry を使うと、次のスケジュール済みリトライを数時間または数日待たずに、すぐに 1 回試行できます。 * **更新決済のみ**: Manual Retry は、サブスクリプションが `on_hold` の間の、サブスクリプション更新 invoice に適用されます。初回決済、1 回限りの決済、プラン変更による請求、オンデマンドの請求は対象外です。 * **顧客による操作は不要**: サブスクリプションにすでに保存されている決済手段に請求します。 * **自動リトライとは独立**: 手動リトライは自動スケジュールの試行回数を消費せず、次回のスケジュール済みリトライを移動させず、Payment Retries が無効の場合でも機能します。 * **決済ではなく invoice を再試行**: 失敗した決済は入口にすぎません。Dodo Payments はその背後にある未払いの更新 invoice を検索して請求するため、invoice 上のどの失敗した決済から再試行するかは問題になりません。 ## ダッシュボードからの再試行 **Transactions → Payments** に移動し、失敗した更新決済をクリックして **Transaction details** ページを開きます。 右上の **Retry Payment Manually** をクリックします。このボタンは、決済が[対象](#eligibility)である間のみ使用できます。 試行のために新しい決済が作成され、**Activity Log** に表示されます。請求が成功すると、サブスクリプションは `active` に戻り、次回の請求日は通常どおり進みます。決済プロセッサがまだ請求を確定していない場合、`payment.succeeded` または `payment.failed` webhook が結果を通知するまで、決済は処理中として表示されます。 エラーコードとメッセージ、Activity Log、Retry Payment Manually ボタンが表示された失敗決済の Transaction details ページ ## 対象条件 以下のすべてのチェックに合格した場合のみ、手動リトライが送信されます。**Reason code** 列は API が返す値です。`GET /payments/{payment_id}/retry` では `reason` として、`POST /payments/{payment_id}/retry` では `code` エラーとして返されます。 | チェック | 要件 | Reason code | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | 決済タイプ | invoice がまだ open であるサブスクリプションの**更新**決済。invoice がない決済、初回決済、1 回限りの決済、プラン変更による請求、オンデマンドの請求は再試行できません。 | `PAYMENT_NOT_RETRYABLE` | | サブスクリプションのステータス | `on_hold` | `SUBSCRIPTION_INACTIVE` | | スケジュール済みキャンセル | 次回請求日にサブスクリプションがキャンセルされる予定ではない。 | `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` | | 保存済みの決済手段 | 請求できる保存済みの決済手段がサブスクリプションにある。 | `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD` | | 直近の失敗 | 最新の失敗が**ソフトディクライン**である。ハードディクライン、または分類済みのエラーコードがない失敗は再試行できません。 | `MANUAL_RETRY_HARD_DECLINE` | | 処理中の決済がない | invoice 上の決済が `processing` でなく、ステータス未記録でもない。これは、手動または自動で直前に送信され、まだ結果を返していない試行です。まず結果を待ってください。 | `MANUAL_RETRY_IN_FLIGHT` | | 最新の決済が失敗している | invoice 上の最新の決済のステータスが `failed` である。`requires_customer_action`、`requires_payment_method`、`cancelled` など、`failed` 以外の状態の最新決済がある場合、処理中の決済がなくてもリトライはブロックされます。 | `PREVIOUS_PAYMENT_PENDING` | | すでに支払い済みでない | invoice 上の決済が成功していない。 | `MANUAL_RETRY_ALREADY_PAID` | | リトライ上限 | invoice に対して送信済みの手動リトライが 3 回未満で、クールダウンが経過している。[Retry Limits](#retry-limits) を参照してください。 | `MANUAL_RETRY_LIMIT_REACHED` | | 顧客 | 顧客が[ブロックリスト](/features/customer-blocklist)に登録されていない。 | `PAYMENT_NOT_RETRYABLE` | | 決済コネクタ | [BYOP](/features/byop) サブスクリプションの場合、コネクタが有効になっている。 | `BYOP_CONNECTOR_DISABLED` | | Live mode | Live mode で、ビジネスの live payments が有効になっている。 | `MERCHANT_NOT_LIVE` | Manual Retry は、自動リトライよりも 1 つの点で対象範囲が狭く、サブスクリプションが `on_hold` であることが必要です。自動リトライは、active 以外の他のステータスでも実行されます。[Subscription Status Transitions](/features/recovery/payment-retries#subscription-status-transitions) を参照してください。 同じカードに対してハードディクラインを再試行しても成功する可能性はなく、ディクラインを繰り返すと承認率が低下します。Reason が `MANUAL_RETRY_HARD_DECLINE` の場合は、顧客に決済手段の更新を依頼してください。[Subscription Dunning](/features/recovery/subscription-dunning) はこれを自動的に行います。 ## リトライ上限 各更新 invoice では、手動リトライを**3 回**まで実行でき、各リトライの間にはクールダウンがあります。 | 手動リトライ | 利用可能になるタイミング | | ------ | ------------ | | 1 | 決済が対象になるとすぐ | | 2 | 1 回目の 1 時間後 | | 3 | 2 回目の 3 時間後 | この上限は test mode と live mode の両方に適用されます。この理由でリトライが拒否されると、API は `MANUAL_RETRY_LIMIT_REACHED` (HTTP `429`) を返します。エラー body には `code` と `message` のみが含まれます。次回のリトライがいつ可能になるかを確認するには、[リトライ状態を確認](#check-whether-a-payment-can-be-retried)し、`retry_available_at` を読み取ってください。3 回すべてを使い切ると `null` になります。 自動リトライはこの上限にカウントされず、手動リトライも自動スケジュールの 8 回の試行にはカウントされません。 ## 手動リトライと自動リトライの比較 | | Manual Retry | Payment Retries | | --------------------------- | ----------------------------------------------- | ------------------------------------ | | **トリガー** | ダッシュボードまたは API からのユーザー操作 | Dodo Payments がバックオフスケジュールに従って実行 | | **タイミング** | 直ちに | 失敗の 12 時間後、その後は段階的に遅くなる | | **試行回数** | invoice ごとに 3 回。クールダウンは 1 時間、次に 3 時間 | recovery window 内で invoice ごとに最大 8 回 | | **Payment Retries の有効化が必要** | いいえ | はい | | **相互への影響** | なし。手動リトライの失敗によって自動試行がスケジュールされたり移動したりすることはありません。 | なし。手動送信の有無にかかわらず、自動チェーンは継続します。 | | **Analytics** | Recovery タブの **Payment retries** metrics にカウント | 同じ metrics にカウント | ## API を使用した再試行 まず対象条件を確認し、その後リトライを送信します。どちらの endpoint も失敗した決済の ID を受け取ります。 ### 決済が再試行可能か確認する `GET /payments/{payment_id}/retry` は、対象外の決済に対して失敗することはありません。代わりに `reason` code とともに `can_retry: false` を返すため、ダッシュボードやサポートツールで Dodo Payments ダッシュボードと同じ状態を表示できます。**Viewer** role が必要です。 ```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" } ``` | フィールド | 説明 | | -------------------- | --------------------------------------------------------------- | | `can_retry` | 今すぐリトライが送信される場合は `true`。 | | `reason` | リトライが失敗する場合の code。`can_retry` が `true` の場合は `null`。 | | `sends_used` | この invoice に対してすでに送信された手動リトライの回数。 | | `sends_allowed` | 常に `3`。 | | `retry_available_at` | 次回の手動リトライが可能になる時刻。リトライが残っていない場合、または拒否理由がクールダウンに関係しない場合は `null`。 | ### 手動リトライを送信する `POST /payments/{payment_id}/retry` は新しい決済を作成し、保存済みの決済手段に請求します。**Editor** role が必要です。 ```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" } ``` | フィールド | 説明 | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `payment_id` | この試行のために作成された新しい決済。 | | `invoice_id` | 請求された更新 invoice。 | | `status` | 請求の結果。`processing` は、プロセッサがまだ確定していないことを意味します。`null` は、response が返される前に結果が記録されなかったことを意味します。どちらの場合も、決済 webhook が最終結果を通知します。 | | `retry_attempt` | invoice 上の手動リトライの中での、この試行の位置。`1` から開始します。 | | `is_manual_retry` | この endpoint では常に `true`。 | | `sends_used`、`sends_allowed`、`retry_available_at` | この送信後のリトライ上限の状態。`retry_available_at` はクールダウンの時計のみを示します。この請求が成功した場合でも設定され、その場合 invoice は支払い済みとなり、それ以降のリトライは可能になりません。 | ### エラーレスポンス | HTTP status | Codes | 対応 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `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` | この決済は再試行できません。call を繰り返さないでください。 | | `429` | `MANUAL_RETRY_LIMIT_REACHED` | [リトライ状態を確認](#check-whether-a-payment-can-be-retried)し、`retry_available_at` になるまで待つか、3 回すべてのリトライを使い切った時点で停止してください。 | すべての code については、[Error Codes](/api-reference/error-codes) reference で説明しています。 ## Webhooks Manual Retry は通常の決済を作成するため、他の更新試行と同じ webhook が発火します。 | Event | 発火するタイミング | | -------------------- | --------------------------------------------------------------------- | | `payment.succeeded` | リトライの請求が行われたとき。サブスクリプションが再有効化される際に `subscription.active` が続きます。 | | `payment.failed` | リトライが拒否されたとき。サブスクリプションは `on_hold` のままで、手動リトライの失敗から自動リトライはスケジュールされません。 | | `payment.processing` | プロセッサが請求を受け付けたものの、まだ確定していないとき。 | これらの event の payment object では、`retry_attempt` は `1` 以上で、`subscription_id` が設定されます。これは自動リトライの場合とまったく同じです。手動試行とスケジュール済み試行を区別する必要がある場合は、リトライ response の `payment_id` を保持してください。 決済 event の完全な payload schema。 ## 関連情報 手動リトライと並行して実行される自動バックオフスケジュール。 ハードディクライン後に決済手段を更新するよう顧客にメールします。 ディクラインコードを読み取り、リトライする価値があるタイミングを判断します。 すべての `MANUAL_RETRY_*` code、そのトリガー、メッセージ。