결제 실패 처리

결제가 실패하면 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를 고객에게 안전한 문구로 매핑하세요(Surface Errors to Customers Safely 참조).

`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"
    }
  }
}

최소한의 handler는 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 signature를 확인하세요. signature verification과 idempotency를 포함한 전체 설정 방법은 Webhooks guide를 참조하세요.

재시도 여부 결정: Soft Declines와 Hard Declines

error_code는 동일한 payment method로 재시도할 가치가 있는지 알려줍니다.

거절 유형	예시	조치
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	잠시 후 또는 고객이 입력 정보를 수정한 후 재시도합니다.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	동일한 카드로 재시도하지 마세요. 고객에게 다른 결제 수단을 요청하세요.

거절 유형과 권장 조치의 전체 목록은 Transaction Failures를 참조하세요.

Checkout과 Renewal에서의 실패 처리

복구 방법은 고객이 현재 결제 과정에 참여하고 있는지에 따라 달라집니다.

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

고객이 현재 checkout을 진행 중입니다. 명확한 메시지를 표시하고 다시 시도하거나 다른 카드를 사용할 수 있도록 하세요.

requires_payment_method — 고객이 결제 수단을 제공하지 않았습니다. 일반적으로 이는 거절이 아니라 checkout 이탈입니다. 결제를 완료할 수 있도록 고객을 다시 유도하세요(Abandoned Cart Recovery 참조).
requires_customer_action — 추가 인증(예: 3DS)이 필요합니다. 고객이 인증을 완료하도록 안내하세요. 3D Secure를 참조하세요.

고객이 현재 자리에 없습니다. 갱신에 실패하면 구독은 on_hold로 전환되고 subscription.on_hold가 실행됩니다. 비즈니스에 유예 기간이 있는 경우 먼저 past_due(subscription.past_due)로 전환되며, 유예 기간이 끝날 때까지 액세스가 유지됩니다.

Subscription Payment Retries를 활성화하면 예약된 갱신의 Soft decline이 자동으로 재시도됩니다(기본적으로 비활성화됨). 재시도는 예약된 갱신에만 적용되며 주문형 청구에는 적용되지 않습니다.
예약된 갱신에서 발생한 Hard decline(및 재시도 소진)은 Subscription Dunning을 통해 복구되며, 고객에게 결제 수단을 업데이트하라는 이메일이 전송됩니다. 주문형 청구 실패에 대해서는 On-Demand Subscriptions을 참조하세요.

전체 on-hold → reactivate 흐름은 Subscription Integration Guide를 참조하세요.

실패한 결제 재시도

구독: Subscription Payment Retries를 활성화하면 Soft decline을 자동으로 복구할 수 있습니다. 일정을 기다리지 않고 즉시 재시도하려면 dashboard 또는 API에서 Manual Payment Retry를 사용하세요. Update Payment Method API를 통해 고객이 결제 수단을 업데이트하도록 하여 복구를 트리거할 수도 있으며, 이 경우 미납 금액이 청구됩니다. 일회성 결제: 고객이 다른 결제 수단으로 다시 시도할 수 있도록 checkout 또는 payment_link를 다시 전송하세요. 일회성 결제에는 자동 재시도가 없습니다.

동일한 카드로 Hard decline을 재시도하지 마세요. 카드 네트워크는 반복되는 거절을 악의적인 행위로 표시하므로 authorization rate에 악영향을 줍니다.

고객에게 오류를 안전하게 표시하기

고객에게 친절한 메시지를 표시하고, 원시 error_code 또는 판매자용 error_message는 절대 표시하지 마세요.

Dodo Payments가 관리하는 화면(checkout, Customer Portal, dunning 이메일)에서는 사기와 관련된 거절에 대한 일반 메시지로의 fallback을 포함하여 이 매핑이 이미 처리되어 있습니다. 자체 제품에서 실패를 표시하는 경우에만 아래 매핑을 사용하면 됩니다.

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

결제 이벤트의 전체 payload 스키마입니다.

Testing Failures

거절 및 갱신 실패를 시뮬레이션하는 테스트 카드입니다.

Integration Guides

Billing Deconstructions

Cookbooks

Dodo Payments이 실패를 보고하는 방식

`payment.failed` Webhook

재시도 여부 결정: Soft Declines와 Hard Declines

Checkout과 Renewal에서의 실패 처리

실패한 결제 재시도

고객에게 오류를 안전하게 표시하기

관련 문서

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Dodo Payments이 실패를 보고하는 방식

​payment.failed Webhook

​재시도 여부 결정: Soft Declines와 Hard Declines

​Checkout과 Renewal에서의 실패 처리

​실패한 결제 재시도

​고객에게 오류를 안전하게 표시하기

​관련 문서

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Dodo Payments이 실패를 보고하는 방식

`payment.failed` Webhook

재시도 여부 결정: Soft Declines와 Hard Declines

Checkout과 Renewal에서의 실패 처리

실패한 결제 재시도

고객에게 오류를 안전하게 표시하기

관련 문서