支払い失敗の処理

決済が失敗すると、Dodo Payments は標準化された error_code と、人が読める error_message を提供します。このガイドでは、これらのフィールドの読み取り方法、再試行するかどうかの判断方法、決済を安全に回復する方法を説明します。

Dodo Paymentsが報告する障害の方法

失敗したすべての決済では、決済オブジェクトに次のフィールドが含まれます。

フィールド	型	説明
`status`	string	失敗した決済の `failed`。その他の成功以外の状態: `cancelled`、`requires_customer_action`、`requires_payment_method`。
`error_code`	string \| null	標準化された失敗理由。例: `INSUFFICIENT_FUNDS` または `PROCESSING_ERROR`。完全な一覧は Transaction Failures を参照してください。
`error_message`	string \| null	推奨アクションを含む、マーチャント向けの説明。顧客には表示しないでください。
`retry_attempt`	integer	元の請求に対する `0`。スケジュールされたサブスクリプション更新の再試行では、`1` 以上になります。

error_code と error_message は、決済が失敗するまで null です。必ず最初に status を確認してください。

error_message はマーチャント向けの情報であり、不正に関連する理由が明らかになる可能性があります。顧客には決して表示しないでください。代わりに error_code を顧客向けに安全な文言へマッピングします（顧客にエラーを安全に表示するを参照）。

`payment.failed` Webhook

payment.failed webhook は、失敗を検出する最も信頼性の高い方法です。このイベントでは、完全な決済オブジェクトが data にラップされています。

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

最小限のハンドラーで error_code を読み取り、その値に基づいて処理を振り分けます。

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

処理する前に、必ずwebhookの署名を検証してください。署名検証や冪等性を含む完全な設定方法については、Webhooks guideを参照してください。

再試行するかどうかを判断する：Soft declineとHard decline

error_codeは、同じ支払い方法で再試行する価値があるかどうかを示します。

ディクラインの種類	例	アクション
ソフトディクライン	`INSUFFICIENT_FUNDS`、`PROCESSING_ERROR`、`NETWORK_ERROR`、`TRY_AGAIN_LATER`	遅延後、または顧客が入力内容を修正した後に再試行します。
ハードディクライン	`STOLEN_CARD`、`LOST_CARD`、`PICKUP_CARD`、`DO_NOT_HONOR`、`FRAUDULENT`、`INVALID_ACCOUNT`	同じカードで再試行しないでください。顧客に別の決済手段を使用してもらいます。

ディクラインの種類と推奨アクションの完全な一覧は、Transaction Failures を参照してください。

Checkout時と更新時の失敗への対応

顧客がその場にいるかどうかによって、回復方法は異なります。

At checkout (customer present)
On subscription renewal (customer not present)

顧客は現在 checkout を進めています。わかりやすいメッセージを表示し、再試行するか別のカードを使用できるようにしてください。

requires_payment_method — 顧客が決済手段を提供しなかったことを示します。通常、これはディクラインではなく checkout の離脱です。顧客に再度アプローチして決済を完了してもらいます（放棄カートの回復を参照）。
requires_customer_action — 追加の認証（3DS など）が必要です。顧客に認証を完了してもらいます。3D Secure を参照してください。

顧客はその場にいません。更新に失敗すると、サブスクリプションは on_hold に移行し、subscription.on_hold が発火します。ビジネスに猶予期間がある場合は、まず past_due（subscription.past_due）に移行し、猶予期間が終了するまでアクセスを維持します。

ソフトディクラインは、Subscription Payment Retries を有効にすると自動的に再試行されます（デフォルトでは無効）。再試行の対象はスケジュールされた更新のみで、オンデマンドの請求は対象外です。
スケジュールされた更新でのハードディクライン（および再試行回数を使い切った場合）は、Subscription Dunning によって回復します。顧客に決済手段の更新を依頼するメールが送信されます。オンデマンドの請求失敗については、On-Demand Subscriptions を参照してください。

保留中から再有効化までの完全なフローは、Subscription Integration Guide を参照してください。

失敗した支払いの再試行

サブスクリプション: Subscription Payment Retries を有効にすると、ソフトディクラインを自動的に回復できます。スケジュールを待たずにすぐ再試行するには、ダッシュボードまたは API から Manual Payment Retry を使用します。また、Update Payment Method API を使用して顧客に決済手段を更新してもらうことで、未払いの料金を請求し、回復を開始することもできます。 一回限りの決済: checkout または payment_link を再送信し、顧客が別の決済手段で再試行できるようにします。一回限りの決済には自動再試行はありません。

同じカードに対してハードディクラインを再試行しないでください。カードネットワークは繰り返されるディクラインを不正利用とみなすため、承認率が低下します。

顧客にエラーを安全に表示する

顧客には親しみやすいメッセージを表示し、raw の error_code やマーチャント向けの error_message は決して表示しないでください。

Dodo Payments が管理する画面（checkout、Customer Portal、督促メール）では、不正に関連するディクラインに対する汎用メッセージへのフォールバックを含め、このマッピングがすでに行われています。以下のマッピングが必要なのは、自社のプロダクトで失敗を表示する場合のみです。

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

STOLEN_CARD、LOST_CARD、PICKUP_CARD、または FRAUDULENT の実際の理由を決して明らかにしないでください。これらを表示すると、不正行為者に手がかりを与える可能性があります。汎用的なディクラインメッセージを表示し、具体的な error_code は内部でのみログに記録してください。

Transaction Failures

すべてのディクラインコード、その種類、推奨アクション。

Error Codes

カードのディクラインではない API およびビジネスロジックのエラー。

Subscription Payment Retries

サブスクリプション更新時のソフトディクラインを自動的に回復します。

Subscription Dunning

ハードディクラインを回復するメールシーケンス。

Payment Webhooks

決済イベントの完全な payload スキーマ。

Testing Failures

ディクラインと更新失敗をシミュレートするテストカード。

Integration Guides

Billing Deconstructions

Cookbooks

Dodo Paymentsが報告する障害の方法

`payment.failed` Webhook

再試行するかどうかを判断する：Soft declineとHard decline

Checkout時と更新時の失敗への対応

失敗した支払いの再試行

顧客にエラーを安全に表示する

関連情報

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Dodo Paymentsが報告する障害の方法

​payment.failed Webhook

​再試行するかどうかを判断する：Soft declineとHard decline

​Checkout時と更新時の失敗への対応

​失敗した支払いの再試行

​顧客にエラーを安全に表示する

​関連情報

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Dodo Paymentsが報告する障害の方法

`payment.failed` Webhook

再試行するかどうかを判断する：Soft declineとHard decline

Checkout時と更新時の失敗への対応

失敗した支払いの再試行

顧客にエラーを安全に表示する

関連情報