Skip to main content

​
概要

Dodo Payments は、支払いの試行が失敗するたびに詳細な失敗理由を返します。これらの理由は決済手段やプロバイダーを問わず標準化されているため、アプリケーションで一貫した処理を実装できます。 支払いが失敗すると、payment.failed webhook と payment object には次の情報が公開されます。
  • error_code — 以下の表に記載された標準化された失敗理由。
  • error_message — 人間が読める説明。
  • retry_attempt — 元の charge では 0、スケジュールされた subscription renewal の各リトライでは 1 以上。
これらの失敗理由を理解すると、顧客に明確なフィードバックを提供し、リトライする価値があるかを判断し、より多くの収益を回収できます。

Handle Payment Failures

webhook と API からこれらのコードを読み取り、顧客に表示し、リトライするタイミングを判断するための、ステップごとの開発者向けガイドです。

​
ソフトディクラインとハードディクライン

すべての失敗コードは、2つのカテゴリーのいずれかに分類されます。この区別によって、同じ決済手段でリトライするか、顧客に新しい決済手段を求めるかが決まります。 subscription renewal では、Dodo Payments がこの区別を自動的に適用します。ソフトディクラインは Subscription Payment Retries によって再試行され、ハードディクラインはリトライチェーンを直ちに終了します。ハードディクラインには Subscription Dunning による対応が適しています。
STOLEN_CARD、LOST_CARD、PICKUP_CARD、または FRAUDULENT の実際の理由を顧客に決して明かさないでください。 これらを表示すると、不正行為者に手がかりを与える可能性があります。顧客には常に一般的なディクラインメッセージ（例：「カードが拒否されました。銀行に問い合わせるか、別のカードを使用してください。」）を表示し、具体的なコードは内部でのみ記録してください。

​
トランザクション失敗の理由

次の表には、すべての失敗コード、ディクラインの種類、顧客が解決できるかどうか、説明、および推奨アクションを記載しています。
User Error は、顧客が支払いのディクラインを解決できるかどうかを示します。Yes の場合、顧客は問題を解決するためのアクションを実行できます（例：正しいカード情報を入力する）。No の場合、ディクラインの原因はシステムレベルの問題または銀行側の制限であり、顧客が直接解決することはできません。
発行銀行独自のrisk engineが、merchantやトランザクションの詳細とは無関係に、カード名義人を高リスク顧客としてフラグ付けした場合にも、カードは拒否されることがあります。通常、このようなディクラインには DO_NOT_HONOR、GENERIC_DECLINE、CARD_DECLINED、TRANSACTION_NOT_APPROVED、または FRAUDULENT のような一般的なコードが表示されます。この場合、銀行は具体的な理由を共有せず、Dodo Payments もmerchantも決定を覆すことはできません。顧客に銀行へ問い合わせてフラグを解消するか、別のカードまたはpayment methodを使用するよう依頼します。

​
プログラムによる失敗処理

payment.failed webhookまたはpayment objectから error_code を読み取り、上記の推奨アクションに対応付けて、リトライするかどうかを判断します。subscription renewalでは、ソフトディクラインは自動的にリトライされます。Subscription Payment Retriesを参照してください。 カードのディクラインではないAPIレベルおよびビジネスロジックのエラー（PAYMENT_NOT_SUCCEEDED や REFUND_WINDOW_EXPIRED など）については、Error Codes リファレンスを参照してください。

​
関連

Handle Payment Failures

失敗した支払いを検出、表示、リトライするためのエンドツーエンドガイドです。

Error Codes

ディクライン以外の失敗に関するAPIおよびビジネスロジックのエラーコードです。

Subscription Payment Retries

subscription renewalでソフトディクラインを回復する自動リトライです。

Subscription Dunning

payment methodの更新を促してハードディクラインを回復するメールシーケンスです。

​
サポート

トランザクション失敗またはintegration issuesについてさらにサポートが必要な場合は、support@dodopayments.com までサポートチームにお問い合わせください。
最終更新日 2026年7月31日