支払い失敗の処理

支払いが失敗したとき、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	失敗についての、人が読める説明。顧客向けではなく、加盟店向けに記述されています。標準化された`error_code`の場合、プロセッサーから返された生のテキストではなく、見出しと推奨アクションが含まれます。
`retry_attempt`	integer	元の請求に対する`0`。`1`以上の場合、スケジュールされたサブスクリプション更新の再試行を示します。

error_codeとerror_messageは支払いが実際に失敗するまでnullです。最初にstatusを常に確認し、次にエラーフィールドを読み取ります。

Merchant APIのerror_messageは、加盟店向けの文言です。詐欺に関連するものを含め、拒否の実際の理由が示される場合があるため、顧客に直接表示しないでください。代わりに、Surface Errors to Customers Safelyに示すように、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 renewal — Dodo retries soft declines for you
      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 renewal — Dodo retries soft declines for you
            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は、同じ支払い方法で再試行する価値があるかどうかを示します。

拒否タイプ	意味	対応
Soft decline	一時的、または修正可能な拒否（例：`INSUFFICIENT_FUNDS`、`PROCESSING_ERROR`、`NETWORK_ERROR`、`TRY_AGAIN_LATER`）。	時間を置いて再試行するか、顧客が入力を修正した後に再試行すると、成功する可能性があります。
Hard decline	終端状態の拒否（例：`STOLEN_CARD`、`LOST_CARD`、`DO_NOT_HONOR`、`FRAUDULENT`）。	同じカードで再試行しないでください。顧客に別の支払い方法を依頼してください。

Transaction Failuresリファレンスには、すべてのerror_codeについて、拒否タイプと推奨アクションが記載されています。

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

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

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

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

requires_payment_method — 顧客が支払い方法を一度も提示していない状態です。カード情報を入力しなかったか、入力を求められたものの何も操作しなかったことを意味します。通常、これは拒否ではなくCheckoutからの離脱です。Abandoned Cart Recoveryを参照し、支払いを完了してもらうために顧客へ再度アプローチしてください。
requires_customer_action — 追加の認証（3DSなど）が必要です。顧客に認証を完了してもらってください。3D Secure handlingを参照してください。

顧客がその場にいないため、リアルタイムで操作を促すことはできません。更新に失敗すると、サブスクリプションはon_holdに移行し、subscription.on_holdが発生します。

Soft declineは、Subscription Payment Retriesによって自動的に再試行されます。
Hard decline（および再試行回数を使い果たした場合）は、Subscription Dunningで回復するのが最適です。顧客に支払い方法の更新を依頼するメールが送信されます。

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

失敗した支払いの再試行

サブスクリプション： Subscription Payment Retriesを有効にすると、追加の連携作業なしでSoft declineを回復できます。Update Payment Method APIを使用して顧客に支払い方法を更新してもらうことでも、回復を開始できます。このAPIは未払いの料金を請求します。
1回限りの支払い： Checkoutまたはpayment_linkを再送信し、顧客が別の方法で再試行できるようにします。1回限りの支払いには自動再試行はありません。

同じカードに対してHard declineの再試行を行わないでください。カードネットワークによって、繰り返される拒否が不正な行為として検知される可能性があり、承認率の低下につながります。

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

顧客には親しみやすいメッセージを表示してください。生の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

サブスクリプション更新時のSoft declineの自動回復。

Subscription Dunning

Hard declineを回復するメールシーケンス。

Payment Webhooks

支払いイベントの完全なペイロードスキーマ。

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時と更新時の失敗への対応

失敗した支払いの再試行

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

関連情報