支払い失敗の処理 - Dodo Payments Documentation

支払いが失敗したとき、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`。完全なリストは取引失敗リファレンスを参照してください。
`error_message`	string \| null	失敗の人間が読める説明。
`retry_attempt`	integer	元の請求に対する`0`。`1`以上はスケジュールされたサブスクリプション更新の再試行を識別します。

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

`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の署名を必ず検証してください。完全な設定には署名の検証と冪等性が含まれていますので、Webhookガイドを参照してください。

再試行するかどうかの決定：ソフト拒否とハード拒否

error_codeは、同じ支払い方法を再試行する価値があるかどうかを教えてくれます。

拒否タイプ	意味	すべきこと
ソフト拒否	一時的または修正可能（例えば`INSUFFICIENT_FUNDS`、`PROCESSING_ERROR`、`NETWORK_ERROR`、`TRY_AGAIN_LATER`）。	顧客が入力を修正した後、遅延後に再試行すると成功する可能性があります。
ハード拒否	終局的（例えば`STOLEN_CARD`、`LOST_CARD`、`DO_NOT_HONOR`、`FRAUDULENT`）。	同じカードを再試行しないでください。顧客に別の支払い方法を尋ねてください。

取引失敗リファレンスには、すべてのerror_codeの拒否タイプと推奨操作が記載されています。

チェックアウトでの失敗と更新時の失敗の処理

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

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

顧客が積極的にチェックアウトしています。明確なメッセージを表示し、すぐに再試行するか、別のカードを使用してもらいます。

requires_payment_method — 顧客が支払い方法を提供しなかった：カードの詳細を入力しなかったか、プロンプトが表示されたか、何の行動も取らなかった。これは通常、チェックアウトドロップオフであり、拒否ではありません — 顧客を再びエンゲージして支払いを完了させます（放棄されたカートの回収を参照してください）。
requires_customer_action — 追加の認証（例えば3DS）が必要です。顧客にそれを完了させます。3D Secureの処理を参照してください。

顧客がその場にいないため、リアルタイムでプロンプトを表示できません。更新が失敗した場合、サブスクリプションはon_holdに移り、subscription.on_holdが発生します。

ソフト拒否は、サブスクリプション支払い再試行によって自動的に再試行されます。
ハード拒否（および再試行が尽きた場合）は、顧客に支払い方法を更新するようメールで通知するサブスクリプション追徴で回収するのが最適です。

サブスクリプション統合ガイドで、保留から再活性化までの完全な流れを参照してください。

失敗した支払いの再試行

サブスクリプション: サブスクリプション支払い再試行を有効にし、統合作業なしでソフト拒否を回収します。また、顧客が支払い方法更新APIを通じて支払い方法を更新し、未払い金額を請求することで回収をトリガーすることもできます。
一度限りの支払い: チェックアウトを再送信するかpayment_linkを実行し、顧客が別の方法で再試行できるようにします。一度限りの支払いに自動再試行はありません。

同じカードへのハード拒否を再試行しないでください。カードネットワークは繰り返される拒否を乱用として旗を立てる可能性があり、承認率に悪影響を与える可能性があります。

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

顧客にフレンドリーなメッセージを表示し、決して生のerror_codeを表示しないでください。

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

支払いイベントのフルペイロードスキーマ。

Testing Failures

拒否と更新失敗をシミュレートするテストカード。

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

​payment.failed Webhook

​再試行するかどうかの決定：ソフト拒否とハード拒否

​チェックアウトでの失敗と更新時の失敗の処理

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

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

​関連情報

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

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

`payment.failed` Webhook

再試行するかどうかの決定：ソフト拒否とハード拒否

チェックアウトでの失敗と更新時の失敗の処理

失敗した支払いの再試行

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

関連情報