오류코드(Error Codes)
KICC API 호출 후 반환되는 resCd (응답 코드)와 resMsg (응답 메시지)를 통해 거래의 성공 여부와 실패 사유를 확인할 수 있습니다.
🟢 성공 코드 (Success)
가장 중요한 코드는 0000 입니다. 이 코드를 수신해야만 정상적으로 결제가 완료된 것입니다.
응답 코드 (resCd) | 메시지 (resMsg) | 설명 |
|---|---|---|
| 0000 | 정상 승인 | 결제, 취소, 조회 등 요청한 작업이 성공적으로 처리됨 |
개발자 체크포인트
resCd가 0000이 아닌 모든 경우는 실패(Failure) 입니다.
실패 시에는 resMsg에 담긴 사유를 확인하여 고객에게 안내하거나 시스템적으로 처리해야 합니다.
🔴 주요 오류 코드 (Failure)
자주 발생하는 오류 코드는 크게 고객 귀책(카드사 거절) 과 상점 설정 문제, 시스템 오류로 나뉩니다.
카드사 거절 (사용자 확인 필요)
고객의 카드 상태나 입력 정보 문제로 거절된 경우입니다. 고객에게 사유를 안내하고 다른 카드로 결제를 유도해야 합니다.
| 코드 | 메시지 예시 | 원인 및 조치 방법 |
|---|---|---|
| 8521 | 한도초과 | 고객의 카드 사용 한도가 부족함 |
| 8035 | 잔액부족 | 체크카드 연결 계좌의 잔액이 부족함 |
| 8314 ~ 8316 | 유효기간 오류 | 카드 유효기간이 만료되었거나 잘못 입력됨 |
| 8311 | 비밀번호 오류 | 카드 비밀번호 입력 오류 (횟수 초과 시 잠김 주의) |
| 8350 | 도난 분실 카드 | 분실 신고된 카드 사용 시도 (즉시 중단) |
| 8373 | 카드사 전화요망 | 카드사 정책상 거래가 거절됨 (고객이 카드사에 문의 필요) |
| 8527 | 포인트 잔액부족 | 카드사 포인트 결제 시 포인트 잔액 부족 (고객이 카드사에 문의 필요) |
개발자 체크포인트
각 결제 서비스 별로 설정에 따라 오류코드가 일부 상이할 수 있으니, 각 결제 서비스 별 아래 오류코드를 참고하시기 바랍니다.
상점 설정 문제로 인한 거절 (영업담당자에게 문의 필요)
상점 등록 시 상점설정 또는 결제수단이 등록되지 않은 경우, 무이자 할부 적용 등으로 발생합니다.
| 코드 | 메시지 예시 | 원인 및 조치 방법 |
|---|---|---|
| P007 | 가맹점 사용불가능한 카드 | [온라인 결제] 상점에서 결제할 수 없는 카드로 결제요청한 경우 발생 |
| P010 | 해외카드 사용불가 가맹점 | [온라인 결제] 해외카드 미사용 가맹점에서 해외카드 결제요청 시 발생 |
| P022 | 무이자 서비스가 가능한 이벤트정보가 아님 | [온라인 결제] 무이자 할부가 없는데 무이자 할부요청을 했을 경우 발생 |
| E201 | 환불 서비스 불가 | [온라인 결제] 상점 설정에 환불 서비스 미사용 되어 있을 경우 발생 |
| E988 | 일반승인 불가 가맹점 | [온라인 결제] 상점이 다중정산 가맹점인데 일반결제를 요청한 경우 발생 |
| A228 | 가맹점 등록 요망 | [VAN 결제] 사용중인 단말기에 이지톡페이가 등록되어 있지 않은 경우 발생 |
시스템 및 통신 오류 (개발자 확인 필요)
네트워크 불안정, 파라미터 오류 등으로 발생합니다.
| 코드 | 메시지 예시 | 원인 및 조치 방법 |
|---|---|---|
| R108 | 중복된 요청 | [온라인 결제] shopTransactionId 값 중복요청으로 발생 (자주묻는 질문 참조) |
| R114 | 메시지 인증값 검증 실패 | [온라인 결제] 메시지 인증값 검증 실패 (자주묻는 질문 참조) |
| R200 | 등록되지 않은 가맹점입니다. | [온라인 결제] 테스트/운영 환경에 맞는 상점ID로 요청필요 (자주묻는 질문 참조) |
| WN14 | 중복된 거래요청 | [온라인 결제] 결제창 호출을 중복으로 요청했을 경우 발생 (자주묻는 질문 참조) |
| TP01 | 결제기관 통신장애 | [온라인 결제] 대외기관 통신오류로 KICC에서 망취소 처리를 함 |
| A200 | 중복된 거래 | [VAN 결제] shopTransactionId 값 중복요청으로 발생 (자주묻는 질문 참조) |
| A220 | 중복된 승인요청 | [VAN 결제] shopTransactionId 값 중복요청으로 발생 (자주묻는 질문 참조) |
| A222 | 미인증 거래 | [VAN 결제] 카드사 앱을 통해 인증을 하지 않고, 승인요청할 경우 발생 |
| A234 | 승인되지 않은 거래 | [VAN 결제] 취소요청 시 승인거래가 없는 경우 발생 |
🛡️ 예외 상황 처리 가이드
결제 시스템 연동 시 가장 주의해야 할 것은 "결과를 모르는 상태(Unknown)" 입니다.
Q. Time Out이 발생하면 어떻게 하나요?
A. 거래상태 조회 API를 이용하여 즉시 망취소(Net Cancel)를 호출하세요.
타임아웃은 "요청은 갔는데 응답이 오다가 끊긴 경우"일 수 있습니다.
실제로는 카드가 긁혔을(승인) 수도 있으므로, 각 결제 서비스별 거래상태 조회 API를 호출하여 거래 상태를 확인하시 바랍니다.