手動決済リトライ

Manual Retry は、決済の詳細ページまたは API からリクエストすると、失敗したサブスクリプションの更新決済を直ちに再試行します。サブスクリプションに保存されている決済手段に請求し、自動の Payment Retries スケジュールとは独立して実行されます。

Manual Retry とは？

更新決済に失敗すると、サブスクリプションは on_hold に移行し、Payment Retries がバックオフスケジュールに従って請求を再試行します。顧客がアカウントへのチャージを確認した場合や、サポートチームが顧客と通話中の場合など、すぐに決済が成功すると分かっていることもあります。Manual Retry を使うと、次のスケジュール済みリトライを数時間または数日待たずに、すぐに 1 回試行できます。

更新決済のみ: Manual Retry は、サブスクリプションが on_hold の間の、サブスクリプション更新 invoice に適用されます。初回決済、1 回限りの決済、プラン変更による請求、オンデマンドの請求は対象外です。
顧客による操作は不要: サブスクリプションにすでに保存されている決済手段に請求します。
自動リトライとは独立: 手動リトライは自動スケジュールの試行回数を消費せず、次回のスケジュール済みリトライを移動させず、Payment Retries が無効の場合でも機能します。
決済ではなく invoice を再試行: 失敗した決済は入口にすぎません。Dodo Payments はその背後にある未払いの更新 invoice を検索して請求するため、invoice 上のどの失敗した決済から再試行するかは問題になりません。

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

Open the failed payment

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

Click Retry Payment Manually

右上の Retry Payment Manually をクリックします。このボタンは、決済が対象である間のみ使用できます。

Check the result

試行のために新しい決済が作成され、Activity Log に表示されます。請求が成功すると、サブスクリプションは active に戻り、次回の請求日は通常どおり進みます。決済プロセッサがまだ請求を確定していない場合、payment.succeeded または payment.failed webhook が結果を通知するまで、決済は処理中として表示されます。

エラーコードとメッセージ、Activity Log、Retry Payment Manually ボタンが表示された失敗決済の Transaction details ページ — Retry Payment Manually on the transaction details page of a failed renewal

対象条件

以下のすべてのチェックに合格した場合のみ、手動リトライが送信されます。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 を参照してください。	`MANUAL_RETRY_LIMIT_REACHED`
顧客	顧客がブロックリストに登録されていない。	`PAYMENT_NOT_RETRYABLE`
決済コネクタ	BYOP サブスクリプションの場合、コネクタが有効になっている。	`BYOP_CONNECTOR_DISABLED`
Live mode	Live mode で、ビジネスの live payments が有効になっている。	`MERCHANT_NOT_LIVE`

Manual Retry は、自動リトライよりも 1 つの点で対象範囲が狭く、サブスクリプションが on_hold であることが必要です。自動リトライは、active 以外の他のステータスでも実行されます。Subscription Status Transitions を参照してください。

同じカードに対してハードディクラインを再試行しても成功する可能性はなく、ディクラインを繰り返すと承認率が低下します。Reason が MANUAL_RETRY_HARD_DECLINE の場合は、顧客に決済手段の更新を依頼してください。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 のみが含まれます。次回のリトライがいつ可能になるかを確認するには、リトライ状態を確認し、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 が必要です。

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`	リトライが失敗する場合の code。`can_retry` が `true` の場合は `null`。
`sends_used`	この invoice に対してすでに送信された手動リトライの回数。
`sends_allowed`	常に `3`。
`retry_available_at`	次回の手動リトライが可能になる時刻。リトライが残っていない場合、または拒否理由がクールダウンに関係しない場合は `null`。

手動リトライを送信する

POST /payments/{payment_id}/retry は新しい決済を作成し、保存済みの決済手段に請求します。Editor role が必要です。

const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

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

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`	請求された更新 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`	リトライ状態を確認し、`retry_available_at` になるまで待つか、3 回すべてのリトライを使い切った時点で停止してください。

すべての code については、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 を保持してください。

Payment Webhook Payloads

決済 event の完全な payload schema。

Subscription Payment Retries

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

Subscription Dunning

ハードディクライン後に決済手段を更新するよう顧客にメールします。

Handle Payment Failures

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

Error Codes

すべての MANUAL_RETRY_* code、そのトリガー、メッセージ。

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

関連情報