결제 실패 처리

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

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

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

Field	Type	Description
`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	고객이 아닌 귀사를 대상으로 작성된, 사람이 읽을 수 있는 실패 설명입니다. 표준화된 `error_code`의 경우 원시 프로세서 텍스트가 아니라 제목과 권장 조치가 포함됩니다.
`retry_attempt`	integer	원래 청구에 대한 `0`입니다. `1` 이상이면 예약된 subscription renewal retry를 나타냅니다.

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

merchant API의 error_message는 merchant-facing copy입니다. 사기와 관련된 경우를 포함해 거절의 실제 사유를 명시할 수 있으므로 고객에게 직접 표시해서는 안 됩니다. 대신 Surface Errors to Customers Safely에 설명된 것처럼 error_code를 자체적으로 정의한 customer-safe 문구에 매핑하세요.

`payment.failed` Webhook

실패를 감지하는 가장 안정적인 방법은 payment.failed webhook입니다. 이벤트는 전체 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를 참조하세요.

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

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

Decline type	What it means	What to do
Soft decline	일시적이거나 수정 가능한 상태입니다(예: `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	일정 시간 후 또는 고객이 입력 내용을 수정한 후 재시도하면 성공할 수 있습니다.
Hard decline	최종적인 상태입니다(예: `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	동일한 card로 재시도하지 마세요. 고객에게 다른 payment method를 요청하세요.

Transaction Failures reference에는 모든 error_code에 대한 decline type과 권장 조치가 나와 있습니다.

Checkout과 Renewal에서의 실패 처리

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

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

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

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

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

Soft declines는 Subscription Payment Retries에 의해 자동으로 재시도됩니다.
Hard declines(및 재시도 횟수를 모두 소진한 경우)는 Subscription Dunning을 사용해 복구하는 것이 가장 좋습니다. 이 기능은 고객에게 payment method 업데이트를 요청하는 이메일을 보냅니다.

보류 상태에서 reactivate하는 전체 흐름은 Subscription Integration Guide를 참조하세요.

실패한 결제 재시도

Subscriptions: Subscription Payment Retries를 활성화하면 별도의 integration 작업 없이 soft declines를 복구할 수 있습니다. 고객이 Update Payment Method API를 통해 payment method를 업데이트하도록 하여 복구를 트리거할 수도 있으며, 이때 미결제 금액이 청구됩니다.
One-time payments: checkout 또는 payment_link를 다시 보내 고객이 다른 method로 다시 시도할 수 있도록 하세요. one-time payments에는 automatic retry가 없습니다.

동일한 card에 대해 hard declines를 재시도하지 마세요. Card networks는 반복적인 decline을 악의적인 행위로 표시할 수 있으며, 이는 authorization rate를 떨어뜨립니다.

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

고객에게는 친절한 메시지를 표시하세요. 원시 error_code나 merchant-facing error_message를 표시해서는 안 됩니다.

Dodo Payments가 관리하는 surface인 checkout, Customer Portal, dunning emails에서는 사기와 관련된 decline에 일반 메시지로 대체하는 처리를 포함해 이 매핑이 이미 완료되어 있습니다. 자체 product에서 실패를 렌더링할 때만 아래 매핑을 사용하면 됩니다.

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의 실제 사유를 절대 공개하지 마세요. 이를 표시하면 사기 행위자에게 유용한 정보를 제공할 수 있습니다. 일반적인 decline 메시지를 표시하고 구체적인 error_code만 내부적으로 기록하세요.

Transaction Failures

모든 decline code, 해당 type 및 권장 조치입니다.

Error Codes

card decline이 아닌 API 및 business-logic errors입니다.

Subscription Payment Retries

subscription renewals에서 soft declines를 자동으로 복구합니다.

Subscription Dunning

hard declines를 복구하는 이메일 sequence입니다.

Payment Webhooks

payment events의 전체 payload schema입니다.

Testing Failures

decline과 renewal failures를 시뮬레이션하는 test cards입니다.

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에서의 실패 처리

실패한 결제 재시도

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

관련 항목