메인 콘텐츠로 건너뛰기

​
개요

Dodo Payments는 결제 시도가 실패할 때마다 자세한 실패 이유를 반환합니다. 이 이유는 결제 방법과 공급자에 따라 표준화되어 있어, 애플리케이션에서 일관된 처리를 구현할 수 있습니다. 결제가 실패하면, payment.failed 웹훅과 결제 객체가 다음을 노출합니다:
  • error_code — 아래 표에서 표준화된 실패 이유.
  • error_message — 사람이 읽을 수 있는 설명.
  • retry_attempt — 원래의 청구에 대한 0, 정기 구독 갱신 재시도마다 1 이상.
이 실패 이유를 이해하면 고객에게 명확한 피드백을 제공하고, 재시도가 가치 있는지 판단하며, 더 많은 수익을 회수할 수 있습니다. A step-by-step developer guide for reading these codes from webhooks and the API, surfacing them to customers, and deciding when to retry.

​
소프트 vs. 하드 거절

모든 실패 코드는 두 가지 범주 중 하나에 속합니다. 이 구분은 동일한 결제 수단을 재시도할지 아니면 고객에게 새로운 수단을 요청할지를 결정하는 데 중요합니다.
거절 유형의미조치예시
소프트 거절임시적이거나 수정 가능 — 동일 카드가 이후 시도에서 성공하거나 고객이 입력을 수정하면 성공할 수 있습니다.안전하게 재시도 (지연 후, 또는 고객이 세부사항을 수정한 경우).INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER
하드 거절최종적 — 동일한 카드를 재시도해도 결과는 바뀌지 않습니다.동일 카드를 재시도하지 마십시오. 고객에게 다른 결제 수단을 사용하거나 은행에 문의하도록 요청하십시오.STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT
구독 갱신의 경우, Dodo Payments는 이 구분을 자동으로 적용합니다: Subscription Payment Retries를 통해 소프트 거절은 재시도되고, 하드 거절은 즉시 재시도가 종료되며, Subscription Dunning으로 가장 잘 처리됩니다. STOLEN_CARD, LOST_CARD, PICKUP_CARD, 또는 FRAUDULENT의 실제 이유를 고객에게 공개하지 마십시오. 이를 노출하면 부정 행위자를 경계하게 될 수 있습니다. 항상 고객에게 일반적인 거절 메시지를 표시하십시오 (예를 들어, “카드가 거절되었습니다. 은행에 문의하거나 다른 카드를 사용하십시오.”) 그리고 내부적으로만 특정 코드를 기록하십시오.

​
거래 실패 이유

다음 표는 모든 실패 코드, 거절 유형, 고객이 해결 가능한지 여부, 설명, 그리고 권장 조치를 나열합니다.
실패 코드유형사용자 오류설명권장 조치
AUTHENTICATION_FAILURE소프트예거래 중 인증 실패고객에게 재시도하고 3DS 인증을 완료하시거나 다른 카드를 사용하도록 요청하십시오
AUTHENTICATION_REQUIRED소프트예추가 인증이 거래를 완료하기 위해 필요합니다고객에게 3DS 인증을 완료하도록 요청하십시오. 구독 갱신의 경우, 고객에게 돌아와서 인증하도록 요청하십시오
AUTHENTICATION_TIMEOUT소프트예인증 과정이 시간 초과되었습니다고객에게 재시도하고 신속히 인증을 완료하도록 요청하십시오
CARD_DECLINED소프트아니요발행 은행이 특별한 이유 없이 카드를 거절했습니다 (일반적인 거절)고객에게 재시도하고, 은행에 문의하거나 다른 카드를 사용하라고 요청하십시오
CARD_NOT_ACTIVATED소프트예카드가 카드 소유자에 의해 활성화되지 않았습니다고객에게 은행에서 카드를 활성화하고 다시 시도하도록 요청하십시오
CARD_VELOCITY_EXCEEDED소프트예짧은 시간 내에 너무 많은 거래 시도고객에게 기다렸다가 다시 시도하도록 요청하거나, 은행에 문의하도록 하십시오
CUSTOMER_CANCELLED소프트예고객이 거래를 취소했습니다고객에게 준비가 되면 결제를 다시 시작하라 하십시오
DO_NOT_HONOR하드아니요발행 은행이 명백히 거래를 거부했습니다 (ISO 8583 코드 05 — 명예 거부); 네트워크는 이를 최종적으로 처리합니다고객에게 은행에 문의하라고 요청하세요; 동일한 카드를 재시도하지 마세요
EXPIRED_CARD하드예카드 만료고객에게 유효한 만료일이 있는 카드를 사용하라고 요청하세요
FRAUDULENT하드예거래가 잠재적 부정 거래로 표시되었습니다고객에게 일반적인 거절 메시지를 표시하고, 이유를 노출하지 마세요. 다른 카드를 사용하라고 요청하세요
GENERIC_DECLINE소프트아니요불특정한 이유로 거래가 거절되었습니다고객에게 은행에 문의하거나 다른 카드를 사용하라고 요청하세요
INCORRECT_CVC소프트예제공된 CVC 코드가 올바르지 않습니다고객에게 올바른 CVC를 다시 입력하라고 요청하세요
INCORRECT_NUMBER소프트예카드 번호가 잘못 입력되었습니다고객에게 올바른 카드 번호를 다시 입력하라고 요청하세요
INSUFFICIENT_FUNDS소프트예계좌에 거래를 완료할 자금이 충분하지 않습니다고객에게 다른 결제 수단을 사용하라고 요청하거나 자금이 확보되면 다시 시도하라 하세요
INVALID_ACCOUNT하드예제공된 계좌 정보가 잘못되었습니다고객에게 은행에 문의하거나 다른 카드를 사용하라고 요청하세요
INVALID_AMOUNT소프트예거래 금액이 유효하지 않습니다고객과 금액 및 구매 제한을 확인하세요
INVALID_CARD_NUMBER소프트예카드 번호 형식이 잘못되었습니다고객에게 유효한 카드 번호를 다시 입력하라고 요청하세요
INVALID_CARD_OWNER소프트예카드 소유자 정보가 유효하지 않습니다고객에게 카드 소지자 이름을 수정하라고 요청하세요
INVALID_CVC소프트예CVC 형식이 잘못되었습니다고객에게 유효한 CVC를 다시 입력하라고 요청하세요
INVALID_EXPIRY_YEAR소프트예카드 만료 연도가 유효하지 않습니다고객에게 유효한 만료일을 입력하라고 요청하세요
INVALID_PIN소프트예제공된 PIN이 잘못되었습니다고객에게 올바른 PIN을 다시 입력하라고 요청하세요
INVALID_REQUEST소프트예거래 요청에 잘못된 데이터가 포함되어 있습니다결제 요청 필드를 확인하고 유효한 데이터로 다시 제출하세요
INVALID_UPI_ID소프트예제공된 UPI ID가 잘못되었습니다고객에게 유효한 UPI ID를 입력하라고 요청하세요
LIMIT_EXCEEDED소프트예거래가 카드 또는 계좌 한도를 초과합니다고객에게 은행에 문의하여 한도를 확인하거나 다른 방법을 사용하라고 요청하세요
LIVE_MODE_TEST_CARD하드예테스트 카드가 라이브 모드에서 사용되었습니다실제 카드를 사용하세요 — 라이브 모드에서는 테스트 카드를 재시도해도 항상 실패합니다
LOST_CARD하드예카드는 분실로 보고되었습니다고객에게 일반적인 거절 메시지를 표시하고, 이유를 노출하지 마세요. 다른 카드를 사용하라고 요청하세요
MANDATE_INVALID소프트예결제 권한이 유효하지 않습니다고객에게 결제 권한을 다시 설정하도록 요청하세요
MANDATE_REQUIRED소프트예이 거래에는 권한이 필요합니다권한을 설정하고 고객에게 요청을 승인하도록 요청한 후에 청구하십시오
MANDATE_REQUIRED_SYSTEM하드아니요시스템은 이 거래 유형에 대한 권한이 필요합니다청구 전에 권한 설정 절차가 완료되었는지 확인하세요
NETWORK_ERROR소프트아니요거래 중 네트워크 오류가 발생했습니다일시적 — 짧은 지연 후 결제를 재시도하십시오
NETWORK_TIMEOUT소프트아니요네트워크 요청이 시간 초과되었습니다일시적 — 짧은 지연 후 결제를 재시도하십시오
ORDER_ALREADY_EXISTS소프트아니요이 거래에 대한 주문이 이미 존재합니다 (중복 주문 생성)기존 주문 상태를 확인한 후에 재시도하십시오; 지속되면 지원팀에 문의하십시오
ORDER_CREATION_FAILED소프트아니요거래에 대한 주문을 생성하는 데 실패했습니다일시적/시스템 오류 — 결제를 재시도하십시오; 지속되면 지원팀에 문의하십시오
PAYMENT_METHOD_PROVIDER_DECLINED하드예결제 수단 제공자가 거래를 거부했습니다고객에게 제공자에게 문의하거나 다른 결제 수단을 사용하라고 요청하세요
PAYMENT_METHOD_UNSUPPORTED하드예이 거래에는 결제 수단이 지원되지 않습니다고객에게 지원되는 결제 수단을 사용하라고 요청하세요
PICKUP_CARD하드예카드는 분실 또는 도난으로 보고되었으며 픽업 대상으로 지정되었습니다고객에게 일반적인 거절 메시지를 표시하고, 이유를 노출하지 마세요. 다른 카드를 사용하라고 요청하세요
PROCESSING_ERROR소프트아니요거래 처리 중 오류가 발생했습니다일시적 — 결제를 재시도하십시오; 지속될 경우 고객에게 은행에 문의하라고 요청하십시오
PROVIDER_UNSUPPORTED하드아니요결제 제공자는 이 거래 유형을 지원하지 않습니다고객에게 다른 결제 수단을 사용하라고 요청하세요
REENTER_TRANSACTION소프트예거래를 다시 입력해야 합니다고객에게 결제를 다시 시도하라고 요청하십시오
REVOCATION_OF_AUTHORIZATION하드예거래 승인 권한이 철회되었습니다고객에게 다른 결제 수단을 사용하라고 요청하십시오
STOLEN_CARD하드예카드는 도난으로 보고되었습니다고객에게 일반적인 거절 메시지를 표시하고, 이유를 노출하지 마세요. 다른 카드를 사용하라고 요청하세요
SUBSCRIPTION_NOT_ACTIVE하드아니요구독이 활성 상태가 아니어서 반복 결제를 처리할 수 없습니다청구 전에 구독(예를 들어 결제 방법 업데이트로)을 재활성화하십시오
TRANSACTION_NOT_ALLOWED하드예이 카드 또는 계좌에서는 거래가 허용되지 않습니다고객에게 은행에 문의하여 이 거래 유형을 허용하게 하거나 다른 카드를 사용하라고 요청하세요
TRANSACTION_NOT_APPROVED하드예거래가 승인되지 않았습니다고객에게 은행에 문의하거나 다른 카드를 사용하라고 요청하십시오
TRY_AGAIN_LATER소프트아니요거래를 나중에 다시 시도해야 합니다일시적 — 결제를 나중에 재시도하십시오
UNKNOWN_ERROR소프트아니요알 수 없는 오류가 발생했습니다결제를 재시도하십시오; 지속되면 지원팀에 문의하세요
사용자 오류는 결제 거절을 고객이 해결할 수 있는지 여부를 나타냅니다. Yes일 때, 고객은 문제를 해결하기 위해 조치를 취할 수 있습니다 (예: 올바른 카드 세부사항 입력). No일 때, 거절은 시스템적 문제나 고객이 직접 해결할 수 없는 은행 제한 때문입니다.

​
실패를 프로그래밍 방식으로 처리하기

error_code를 payment.failed 웹훅 또는 결제 객체에서 읽고, 위에서 권장된 조치에 맵핑한 다음, 재시도할지 여부를 결정하십시오. 정기 구독 갱신의 경우, 소프트 거절은 자동으로 다시 시도됩니다 — Subscription Payment Retries 를 참조하세요. 카드 거절이 아닌 API 수준 및 비즈니스 로직 오류 (예: PAYMENT_NOT_SUCCEEDED 또는 REFUND_WINDOW_EXPIRED)에 대해서는 Error Codes 참고서를 참조하세요.

​
관련 자료

End-to-end guide to detecting, surfacing, and retrying failed payments. API and business-logic error codes for non-decline failures. Automatic retries that recover soft declines on subscription renewals. Email sequences that recover hard declines by prompting a payment method update.

​
지원

거래 실패나 통합 문제에 대한 추가 도움이 필요하면 support@dodopayments.com으로 지원팀에 연락하십시오.
마지막 수정일 2026년 6월 18일