概要
Dodo Payments は、支払いの試行が失敗するたびに詳細な失敗理由を返します。これらの理由は決済手段やプロバイダーを問わず標準化されているため、アプリケーションで一貫した処理を実装できます。 支払いが失敗すると、payment.failed webhook と payment object には次の情報が公開されます。
error_code— 以下の表に記載されている標準化された失敗理由。error_message— マーチャントであるあなた向けに書かれた、人が読める説明。error_codeが以下の標準化コードのいずれかである場合、決済プロセッサからの生のテキストではなく、見出しと推奨アクションが表示されます。retry_attempt— 元の請求に対する0、スケジュールされたサブスクリプション更新の各再試行に対する1以上。
マーチャント向けの文言と顧客向けの文言
すべての標準化された失敗コードは2種類の異なるメッセージに対応しており、適切な対象者に適切な詳細レベルが表示されます。Customer Portal は
error_message に顧客向けの文言を返します。一方、マーチャント API は同じ決済についてマーチャント向けの文言を返します。error_code はどちらでも同一です。Handle Payment Failures
webhook と API からこれらのコードを読み取り、顧客に表示し、再試行のタイミングを判断するための、開発者向けステップバイステップガイドです。
ソフトディクラインとハードディクライン
すべての失敗コードは、2つのカテゴリのいずれかに分類されます。この区別によって、同じ決済手段で再試行するか、顧客に新しい決済手段を求めるかが決まります。
サブスクリプションの更新では、Dodo Payments がこの区別を自動的に適用します。ソフトディクラインはSubscription Payment Retriesによって再試行され、ハードディクラインは再試行チェーンを直ちに終了するため、Subscription Dunningで対応するのが最適です。
取引の失敗理由
以下の表には、すべての失敗コード、ディクラインの種類、顧客が解決できるかどうか、説明、および推奨アクションを記載しています。「ユーザーエラー」は、決済のディクラインを顧客が解決できるかどうかを示します。
Yes の場合、顧客は問題を解決するための対応（例：正しいカード情報を入力する）ができます。No の場合、ディクラインの原因はシステムレベルの問題または銀行の制限であり、顧客が直接解決することはできません。発行銀行独自のリスクエンジンが、マーチャントや取引の詳細とは無関係に、カード所有者を高リスク顧客と判断した場合にも、カードは拒否されることがあります。通常、このようなディクラインは
DO_NOT_HONOR、GENERIC_DECLINE、CARD_DECLINED、TRANSACTION_NOT_APPROVED、または FRAUDULENT のような一般的なコードとして返されます。この場合、銀行は具体的な理由を共有せず、Dodo Payments もマーチャントも判断を覆すことはできません。顧客に銀行へ問い合わせてフラグを解消するか、別のカードまたは決済手段を使うよう依頼してください。プログラムでの失敗処理
payment.failed webhook または payment object から error_code を読み取り、上記の推奨アクションに対応付けて、再試行するかどうかを判断してください。サブスクリプションの更新では、ソフトディクラインが自動的に再試行されます。詳しくはSubscription Payment Retriesを参照してください。
カードのディクラインではない API レベルおよびビジネスロジックのエラー（PAYMENT_NOT_SUCCEEDED や REFUND_WINDOW_EXPIRED など）については、Error Codesリファレンスを参照してください。
関連情報
Handle Payment Failures
失敗した決済の検出、表示、再試行をエンドツーエンドで解説するガイドです。
Error Codes
ディクライン以外の失敗に関する API およびビジネスロジックのエラーコードです。
Subscription Payment Retries
サブスクリプション更新時のソフトディクラインを回復する自動再試行です。
Subscription Dunning
決済手段の更新を促してハードディクラインを回復するメールシーケンスです。