新enum値RETRY_DECLINED追加：決済失敗の原因を正確に把握

11月 06, 2026

GraphQL Admin API

新enum値 RETRY_DECLINED 追加
決済失敗理由をより正確に識別

API 2027-01から、プロセッサーによるリトライ停止を専用の値で区別できるようになります

GraphQL Admin API バージョン 2027-01 以降、CustomerPaymentMethod.revokedReason フィールドが新しい列挙値 RETRY_DECLINED を返すようになります。サブスクリプション決済でプロセッサー側がこれ以上のリトライを拒否した場合に、従来の TOO_MANY_CONSECUTIVE_FAILURES と区別して取得できます。旧バージョンのAPIでは引き続き TOO_MANY_CONSECUTIVE_FAILURES が返ります。

1Before / After：revocationReasonの変化

2業務に活かせる具体ユースケース

課題: サブスクリプション決済が停止したとき、単なる連続失敗なのかプロセッサーに完全拒否されたのかをアプリが区別できず、全ユーザーに同じ「再試行してください」メッセージを出してしまっていた
打ち手: API 2027-01 に移行し、revokedReason === RETRY_DECLINED の場合は「このカードはご利用いただけません。別の支払い方法をご登録ください」と案内するフローに変更する
効果: 無意味な再試行を抑制し、顧客への案内が明確になることでチャーン防止と問い合わせ削減につながる
技術メモ: GraphQLクエリで revokedReason を取得し、switch/caseで RETRY_DECLINED / TOO_MANY_CONSECUTIVE_FAILURES を分岐処理するだけで対応可能

課題: カスタマーサポートチームが決済停止の原因を管理画面上で確認できず、顧客への対応が「とりあえず再登録をお願いします」になっていた
打ち手: 社内管理ツールでサブスクリプション一覧を表示する際、RETRY_DECLINED の場合は「要カード更新」ラベルをサポート担当者に見せるUIを追加する
効果: 初回接触で適切な案内ができるようになり、顧客満足度と解決率が向上する
技術メモ: Webhookを受信後に CustomerPaymentMethod.revokedReason をクエリして値をDBに保存し、管理UIで分類表示する実装が推奨される

課題: TOO_MANY_CONSECUTIVE_FAILURESの場合は数日後に再試行できる可能性があるが、RETRY_DECLINEDは新しい支払い方法が必須であり、同じ自動リトライロジックをそのまま適用すると無駄なAPI呼び出しが発生する
打ち手: 自動リトライスケジューラーに RETRY_DECLINED チェックを追加し、この値が返ってきた場合はリトライをスキップして顧客への通知メールのみ送信するよう制御する
効果: 不要なAPI呼び出しを削減しコスト最適化を図りつつ、プロセッサーへの不要なリクエストも抑制できる
技術メモ: Webhookペイロード自体に変更はないため、既存のWebhookリスナーはそのままに、後続処理でrevokedReasonクエリを追加するだけで対応可能

3技術者向けポイント

項目	詳細	対応状況
対象APIバージョン	GraphQL Admin API 2027-01 以降	要バージョンアップ
旧バージョンの挙動	2026-10以前のAPIでは引き続き `TOO_MANY_CONSECUTIVE_FAILURES` を返す。後方互換性は維持	後方互換あり
Webhookペイロード	`customer_payment_methods/revoke` のペイロード自体に変更なし。Webhook受信後に `revokedReason` を別途クエリする必要あり	変更なし
対象フィールド	`CustomerPaymentMethod.revokedReason`（型：`CustomerPaymentMethodRevocationReason`）	enum拡張
移行時の注意点	2027-01に移行後、`revokedReason` を参照するコードはすべて RETRY_DECLINED ケースのハンドリングを追加する必要がある。未対応だとデフォルト処理に落ちる可能性	要コード修正