개요
Dodo Payments는 결제 시도가 실패할 때마다 자세한 실패 이유를 반환합니다. 이 이유는 결제 방법과 공급자에 따라 표준화되어 있어, 애플리케이션에서 일관된 처리를 구현할 수 있습니다. 결제가 실패하면,payment.failed 웹훅과 결제 객체가 다음을 노출합니다:
error_code— 아래 표에 정의된 표준화된 실패 사유입니다.error_message— 가맹점인 귀하를 위해 작성된 사람이 읽을 수 있는 설명입니다.error_code이 아래의 표준화된 코드 중 하나인 경우, 결제 처리자의 원문이 아니라 제목과 권장 조치를 표시합니다.retry_attempt— 원래 결제에 대한0, 예약된 subscription 갱신 재시도마다1이상입니다.
가맹점용 문구와 고객용 문구
각 표준화된 실패 코드는 서로 다른 두 메시지에 매핑되므로, 대상에 맞는 세부 정보가 표시됩니다:Customer Portal은
error_message에 고객용 문구를 반환하고, merchant API는 동일한 결제에 대해 가맹점용 문구를 반환합니다. error_code은 양쪽에서 동일합니다.Handle Payment Failures
webhook과 API에서 이러한 코드를 읽고, 고객에게 표시하며, 언제 재시도할지 결정하는 단계별 developer guide입니다.
Soft decline과 Hard decline
모든 실패 코드는 두 가지 범주 중 하나에 속합니다. 이 구분에 따라 동일한 payment method를 재시도할지, 고객에게 새로운 payment method를 요청할지가 결정됩니다.
subscription 갱신 시 Dodo Payments는 이 구분을 자동으로 적용합니다. Soft decline은 Subscription Payment Retries를 통해 재시도하고, Hard decline은 재시도 체인을 즉시 종료하므로 Subscription Dunning으로 처리하는 것이 좋습니다.
거래 실패 사유
다음 표에는 모든 실패 코드, decline 유형, 고객이 해결할 수 있는지 여부, 설명 및 권장 조치가 나와 있습니다.User Error는 payment decline을 고객이 해결할 수 있는지 여부를 나타냅니다.
Yes인 경우 고객이 조치를 취해 문제를 해결할 수 있습니다(예: 올바른 카드 세부 정보 입력). No인 경우 decline은 고객이 직접 해결할 수 없는 system-level 문제 또는 은행 제한으로 인해 발생한 것입니다.발급 은행 자체의 risk engine이 가맹점이나 거래 세부 정보와 무관하게 카드 소유자를 high-risk customer로 표시하는 경우에도 카드가 거부될 수 있습니다. 이러한 decline은 일반적으로
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED 또는 FRAUDULENT와 같은 일반 코드로 표시됩니다. 이 경우 은행은 구체적인 사유를 공유하지 않으며 Dodo Payments와 가맹점 모두 해당 결정을 override할 수 없습니다. 고객에게 flag를 해결하려면 은행에 문의하거나 다른 카드 또는 payment method를 사용하도록 요청하세요.Programmatically 실패 처리
payment.failed webhook 또는 payment object에서 error_code을 읽고, 위의 권장 조치에 매핑한 다음 재시도 여부를 결정하세요. subscription 갱신의 경우 Soft decline은 자동으로 재시도됩니다. 자세한 내용은 Subscription Payment Retries를 참조하세요.
카드 decline이 아닌 API-level 및 business-logic error(예: PAYMENT_NOT_SUCCEEDED 또는 REFUND_WINDOW_EXPIRED)는 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입니다.