> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 거래 실패

> 모든 Dodo Payments 거래 실패 코드를 이해하고, 그것이 소프트 또는 하드 거절인지, 그리고 결제를 회복하기 위한 권장 조치를 파악하십시오.

## 개요

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](/features/recovery/payment-retries)를 통해 소프트 거절은 재시도되고, 하드 거절은 즉시 재시도가 종료되며, [Subscription Dunning](/features/recovery/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](/features/recovery/payment-retries) 를 참조하세요.

카드 거절이 아닌 API 수준 및 비즈니스 로직 오류 (예: `PAYMENT_NOT_SUCCEEDED` 또는 `REFUND_WINDOW_EXPIRED`)에 대해서는 [Error Codes](/api-reference/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](mailto:support@dodopayments.com)으로 지원팀에 연락하십시오.

거래 실패 또는 통합 문제에 대한 추가 지원이 필요하시면 [support@dodopayments.com](mailto:support@dodopayments.com)으로 저희 지원팀에 연락해 주세요.