개요
결제 시도가 실패하면 Dodo Payments는 실패 이유를 알려 주는 표준화된 실패 코드를 반환합니다. 이 코드는 결제 수단과 결제 처리업체에 관계없이 동일하므로, 모든 실패한 결제에 하나의 처리 규칙 집합을 적용할 수 있습니다.payment.failed webhook과 payment object에는 실패한 결제에 대한 다음 필드가 포함됩니다:
error_code: 아래 표에 정의된 표준화된 실패 코드입니다.error_message: 결제자, 즉 귀하를 위해 작성된 설명입니다.error_code가 아래의 표준화된 코드 중 하나인 경우, 결제 처리업체의 원문이 아니라 제목과 권장 조치를 표시합니다.retry_attempt: 원래 청구의 경우0이며, 예약된 subscription 갱신 재시도마다1이상입니다. subscription 갱신이 아닌 결제에는0값이 유지됩니다.
가맹점용 문구와 고객용 문구
각 표준화된 실패 코드는 귀하와 고객을 위한 두 가지 메시지에 매핑됩니다:Customer Portal은
error_message에 고객용 문구를 반환하는 반면, merchant API는 동일한 결제에 대해 결제자용 문구를 반환합니다. error_code는 두 곳에서 동일합니다.Handle Payment Failures
webhook과 API에서 이러한 코드를 읽고, 고객에게 표시하며, 언제 재시도할지 판단하는 단계별 developer guide입니다.
Soft decline과 Hard decline
각 실패 코드는 soft decline 또는 hard decline 중 하나입니다. 이 유형을 통해 동일한 결제 정보로 나중에 다시 시도하면 성공할 수 있는지, 아니면 먼저 고객의 조치가 필요한지를 판단할 수 있습니다.
subscription 갱신의 경우 Dodo Payments가 이 분류를 자동으로 적용합니다. Subscription Payment Retries는 soft decline을 다시 시도합니다. hard decline이 발생하면 재시도 체인이 즉시 종료되며, Subscription Dunning을 사용해 회수할 수 있습니다.
거래 실패 사유
다음 표에는 모든 실패 코드와 decline 유형, 고객이 해결할 수 있는지 여부, 설명 및 권장 조치가 나와 있습니다.User Error는 고객이 decline을 해결할 수 있는지 나타냅니다.
Yes는 고객이 올바른 카드 정보를 입력하는 등의 방법으로 문제를 해결할 수 있음을 의미합니다. No는 시스템 수준의 문제 또는 은행 제한으로 인해 decline이 발생했으며, 고객이 직접 해결할 수 없음을 의미합니다.발급 은행은 가맹점이나 거래 세부 정보와 관계없이 자체 위험 엔진이 카드 소유자를 고위험으로 판단하는 경우에도 카드를 거부할 수 있습니다. 이러한 거부는 일반적으로
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED 또는 FRAUDULENT와 같은 일반 코드로 표시됩니다. 은행은 구체적인 사유를 공유하지 않으며, Dodo Payments와 가맹점 모두 이 결정을 번복할 수 없습니다. 고객에게 은행에 문의하여 해당 플래그를 해제하거나 다른 카드 또는 결제 수단을 사용하도록 안내하세요.Programmatically 실패 처리
payment.failed webhook 또는 payment object에서 error_code를 읽고, 표의 권장 조치에 매핑한 다음 재시도 여부를 결정하세요. subscription 갱신의 경우 Dodo Payments가 soft decline을 대신 재시도합니다. Subscription Payment Retries를 참조하세요.
PAYMENT_NOT_SUCCEEDED 또는 REFUND_WINDOW_EXPIRED와 같이 카드 decline이 아닌 API 및 business-logic 오류는 Error Codes reference를 참조하세요.
관련 문서
Handle Payment Failures
실패한 payment를 감지하고 표시하며 재시도하는 end-to-end guide입니다.
Error Codes
Decline이 아닌 실패에 대한 API 및 business-logic error code입니다.
Subscription Payment Retries
subscription 갱신 시 Soft decline을 복구하는 자동 재시도입니다.
Subscription Dunning
payment method 업데이트를 요청하여 Hard decline을 복구하는 이메일 sequence입니다.