결제 실패 처리

결제가 실패하면 Dodo Payments은 표준화된 error_code와 사람이 읽을 수 있는 error_message를 통해 실패 이유를 알려줍니다. 이 가이드에서는 이러한 필드를 읽고, 재시도할 가치가 있는지 판단하며, 고객에게 민감한 정보를 노출하지 않고 결제를 복구하는 방법을 설명합니다.

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

일회성 checkout이든 구독 갱신이든 모든 실패한 결제에는 payment object에 동일한 실패 필드가 포함됩니다.

필드	유형	설명
`status`	string	실패한 결제의 `failed`입니다. 기타 비성공 상태에는 `cancelled`, `requires_customer_action` 및 `requires_payment_method`이 포함됩니다.
`error_code`	string \| null	표준화된 실패 이유입니다. 예: `INSUFFICIENT_FUNDS` 또는 `PROCESSING_ERROR`. 전체 목록은 Transaction Failures reference를 참조하세요.
`error_message`	string \| null	실패에 대한 사람이 읽을 수 있는 설명입니다.
`retry_attempt`	integer	원래 charge에 대한 `0`입니다. `1` 이상이면 예약된 구독 갱신 재시도를 의미합니다.

결제가 실제로 실패하기 전까지 error_code와 error_message는 null입니다. 먼저 항상 status을 확인한 다음 오류 필드를 읽으세요.

`payment.failed` webhook

실패를 감지하는 가장 안정적인 방법은 payment.failed webhook입니다. 이 event는 전체 payment object를 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 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 signature를 검증하세요. signature verification과 idempotency를 포함한 전체 설정 방법은 Webhooks guide를 참조하세요.

재시도 여부 결정: 소프트 거절과 하드 거절

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

거절 유형	의미	조치
소프트 거절	일시적이거나 수정 가능한 상태입니다(예: `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	일정 시간 후 또는 고객이 입력값을 수정한 후 재시도하면 성공할 수 있습니다.
하드 거절	최종적인 상태입니다(예: `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	동일한 card로 재시도하지 마세요. 고객에게 다른 payment method를 요청하세요.

Transaction Failures reference에는 모든 error_code의 거절 유형과 권장 조치가 정리되어 있습니다.

checkout과 갱신 시 실패 처리

복구 방법은 고객이 현재 उपस्थित한 상태인지에 따라 달라집니다.

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

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

requires_payment_method — 고객이 payment method를 제공하지 않았습니다. card details를 입력하지 않았거나, 입력하라는 안내를 받았지만 아무 작업도 하지 않은 경우입니다. 이는 일반적으로 거절이 아니라 checkout 이탈입니다. 결제를 완료하도록 고객에게 다시 참여를 유도하세요(Abandoned Cart Recovery 참조).
requires_customer_action — 추가 authentication(예: 3DS)이 필요합니다. 고객이 이를 완료하도록 안내하세요. 3D Secure handling을 참조하세요.

고객이 현재 자리에 없으므로 실시간으로 안내할 수 없습니다. 갱신이 실패하면 subscription은 on_hold 상태로 이동하고 subscription.on_hold가 실행됩니다.

소프트 거절은 Subscription Payment Retries에 의해 자동으로 재시도됩니다.
하드 거절(및 재시도 소진)은 고객에게 payment method 업데이트를 요청하는 이메일을 보내는 Subscription Dunning으로 복구하는 것이 가장 좋습니다.

전체 보류 → 재활성화 흐름은 Subscription Integration Guide를 참조하세요.

실패한 결제 재시도

Subscriptions: Subscription Payment Retries를 활성화하면 별도의 integration 작업 없이 소프트 거절을 복구할 수 있습니다. 또한 Update Payment Method API를 통해 고객이 payment method를 업데이트하도록 하여 복구를 트리거할 수도 있으며, 이 경우 미납금이 청구됩니다.
One-time payments: 고객이 다른 payment method로 다시 시도할 수 있도록 checkout 또는 payment_link을 다시 보내세요. 일회성 결제에는 자동 재시도가 없습니다.

동일한 card로 하드 거절을 재시도하지 마세요. card network는 반복된 거절을 악의적인 행위로 표시할 수 있으며, 이는 authorization rate에 악영향을 줍니다.

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

고객에게 친절한 메시지를 표시하고, 원시 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

card 거절이 아닌 API 및 business logic 오류입니다.

Subscription Payment Retries

구독 갱신 시 소프트 거절을 자동으로 복구합니다.

Subscription Dunning

하드 거절을 복구하는 이메일 sequence입니다.

Payment Webhooks

payment event의 전체 payload schema입니다.

Testing Failures

거절 및 갱신 실패를 시뮬레이션하는 test card입니다.

Integration Guides

Billing Deconstructions

Cookbooks

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

`payment.failed` webhook

재시도 여부 결정: 소프트 거절과 하드 거절

checkout과 갱신 시 실패 처리

실패한 결제 재시도

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

관련 문서

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

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

​payment.failed webhook

​재시도 여부 결정: 소프트 거절과 하드 거절

​checkout과 갱신 시 실패 처리

​실패한 결제 재시도

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

​관련 문서

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

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

`payment.failed` webhook

재시도 여부 결정: 소프트 거절과 하드 거절

checkout과 갱신 시 실패 처리

실패한 결제 재시도

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

관련 문서