Skip to main content
Manual Retry は、支払いの詳細ページまたは API から指示したときに、失敗したサブスクリプションの更新支払いを再試行します。サブスクリプションに保存されている支払い方法に請求し、自動の Payment Retries スケジュールとは独立して実行されます。

Manual Retry とは?

更新支払いが失敗すると、サブスクリプションは on_hold に移行します。Payment Retries を有効にしている場合は、バックオフスケジュールに従って請求を再試行します。顧客がアカウントへの入金を確認した場合や、サポートチームが顧客と通話中の場合など、今なら支払いが成功すると分かっていることがあります。Manual Retry は、次のスケジュール済みの再試行まで数時間または数日待つ代わりに、すぐに 1 回試行します。
  • 更新支払いのみ: Manual Retry は、サブスクリプションが on_hold の状態にある間、サブスクリプション更新 invoice に適用されます。初回支払い、単発支払い、プラン変更料金、オンデマンド料金は対象外です。
  • 顧客による操作は不要: 請求は、サブスクリプションにすでに保存されている支払い方法に対して行われます。
  • 自動再試行とは独立: Manual Retry は自動スケジュールの試行回数を消費せず、次回のスケジュール済み再試行を移動させず、Payment Retries が無効でも機能します。
  • payment ではなく invoice を再試行: 失敗した payment は入口にすぎません。Dodo Payments はその背後にある未決済の更新 invoice を見つけ、その債務を請求します。そのため、invoice 上のどの失敗した payment から再試行しても問題ありません。

ダッシュボードからの再試行

Owner または Editor ロールを持つユーザーのみ、手動再試行を実行できます。
1

Open the failed payment

Transactions → Payments に移動し、失敗した更新 payment をクリックして Transaction details ページを開きます。
2

Click Retry Payment Manually

右上隅の Retry Payment Manually をクリックします。このボタンは、payment が eligible の間のみ使用できます。
3

Check the result

Dodo Payments は試行用の新しい payment を作成し、それが Activity Log に表示されます。請求が成功すると、サブスクリプションは active に戻り、次回の請求日は、再試行が成功した請求期間の 1 期間後に移動します。決済プロセッサーがまだ請求を確定していない場合、payment は payment.succeeded または payment.failed webhook が結果を報告するまで処理中として表示されます。
エラーコードとメッセージ、Activity Log、Retry Payment Manually ボタンが表示された、失敗した支払いの Transaction details ページ

Retry Payment Manually on the transaction details page of a failed renewal

対象条件

Dodo Payments は、この表のすべてのチェックに合格した場合にのみ手動再試行を送信します。Reason code 列は API が返す値です。GET /payments/{payment_id}/retry の reason として、また POST /payments/{payment_id}/retry のエラー code として返されます。
Manual Retry は、自動再試行よりも範囲が狭い点が 1 つあります。サブスクリプションが on_hold である必要があります。grace period 中の past_due サブスクリプションは、このチェックに失敗します。自動再試行は、その他の非アクティブな status に対しても実行され続けます。Subscription Status Transitions を参照してください。
同じカードに対してハードディクラインを再試行しても成功することはなく、ディクラインが繰り返されると承認率が低下します。理由が MANUAL_RETRY_HARD_DECLINE の場合は、代わりに顧客へ支払い方法の更新を依頼してください。Subscription Dunning はこれを自動的に行います。

再試行の上限

各更新 invoice では、再試行の間にクールダウン期間を設けて、3 回まで手動再試行できます。 この上限は test mode と live mode の両方に適用されます。上限により再試行が拒否されると、API は MANUAL_RETRY_LIMIT_REACHED(HTTP 429)を返し、エラー本文には code と message のみが含まれます。次の再試行がいつ可能になるかを確認するには、再試行の状態を確認 し、retry_available_at を読み取ります。3 回すべての再試行を使い切ると null になります。 自動再試行はこの上限にカウントされず、手動再試行も自動スケジュールの 8 回の試行にはカウントされません。

手動再試行と自動再試行の比較

2 つの再試行方法には、次の違いがあります。

API 経由で再試行

まず対象条件を確認し、その後に再試行を送信します。どちらの endpoint も、失敗した payment の ID を受け取ります。

Payment を再試行できるか確認

GET /payments/{payment_id}/retry は、対象外の payment に対してエラーを返しません。代わりに can_retry: false と reason code を返すため、独自のダッシュボードやサポートツールで Dodo Payments ダッシュボードと同じ状態を表示できます。必要なロールは Viewer です。
Response

手動再試行を送信

POST /payments/{payment_id}/retry は新しい payment を作成し、保存済みの支払い方法に請求します。必要なロールは Editor です。SDK の例では、前の例の client を再利用します。
Response

エラーレスポンス

再試行が許可されない場合、POST は次のいずれかの HTTP status を返します。 Error Codes リファレンスでは、すべての code について説明しています。

Webhooks

Manual Retry は通常の payment を作成するため、他の更新試行と同じ webhooks が発生します。 これらの event の payment object では、retry_attempt は 1 以上で、subscription_id が設定されています。これは自動再試行の場合と同じです。payment object には手動試行を示す field がないため、手動試行とスケジュール済み試行を区別する必要がある場合は、再試行レスポンスの payment_id を保持してください。

Payment Webhook Payloads

payment event の完全な payload schema。

関連情報

Subscription Payment Retries

手動再試行と並行して実行される自動バックオフスケジュール。

Subscription Dunning

ハードディクライン後に支払い方法を更新するよう顧客にメールを送信します。

Handle Payment Failures

ディクラインコードを読み取り、再試行する価値があるタイミングを判断します。

Error Codes

すべての MANUAL_RETRY_* code、そのトリガー、メッセージ。
最終更新日 2026年9月26日