에러 케이스별 가이드

결제 연동 시 자주 발생하는 에러와 해결 방법을 안내합니다.

9010 Hash 데이터 검증 실패

가장 빈번하게 발생하는 오류입니다. 해시(Hash) 생성 시 파라미터가 잘못 구성된 경우 발생합니다.

해결 방법

• 파라미터 순서가 연동 가이드와 일치하는지 확인
• passKey가 환경(개발/운영)에 맞는지 확인
• passKey에 공백이 포함되지 않았는지 확인
• passKey가 대소문자 변환 없이 원본 그대로인지 확인

Hash 생성 순서 참고

이외의 기능들은 연동 가이드에서 확인해주세요.

9713 중복 주문번호

동일한 주문번호로 결제가 두 번 이상 요청됐을 때 발생합니다.

해결 방법

• 주문번호를 요청마다 고유하게 생성

// 방법 1: 타임스탬프 사용
const mxIssueNo = `ORDER_${Date.now()}`;

// 방법 2: UUID 사용 (권장)
import { v4 as uuidv4 } from 'uuid';
const mxIssueNo = `ORDER_${uuidv4()}`;

9013 결제 시간 초과

결제 요청 또는 인증 후 일정 시간이 초과되면 발생합니다.

해결 방법

• 결제창 표시 후 30분 이내에 결제 진행
• 인증 완료 후 24시간 이내에 승인 요청
• 유효시간 초과 시 새로운 결제 시작 안내

P502 원거래 없음

결제 취소 또는 환불 요청 시, 원래 승인 거래를 찾지 못할 때 발생합니다.

해결 방법

• 취소/환불 요청 시 승인 시점의 mxId, mxIssueNo, mxIssueDate 값 사용

// 잘못된 예 - 취소 요청 시점의 시간 사용
String mxIssueDate = LocalDateTime.now().format(formatter); // X

// 올바른 예 - 원거래의 주문일시 사용
Payment originalPayment = paymentRepository.findByOrderId(orderId);
String mxIssueDate = originalPayment.getMxIssueDate(); // O

9003 기초정보 확인 중 오류

가맹점 정보 또는 환경 설정이 잘못 구성된 경우 발생합니다.

해결 방법

• 환경 변수 env가 올바르게 설정되어 있는지 확인
• MID와 passKey가 동일한 환경(개발/운영)에 속하는지 확인
• 요청한 결제수단이 해당 MID에 등록되어 있는지 확인

// 환경별 설정 분리 예시
const config = {
development: {
  env: 'develop',
  mxId: 'testcorp',
  passKey: process.env.DEV_PASS_KEY,
  endpoint: 'https://dev.firstpay.co.kr'
},
production: {
  env: 'product',
  mxId: 'yourcorp',
  passKey: process.env.PROD_PASS_KEY,
  endpoint: 'https://api.firstpay.co.kr'
}
};

const currentConfig = config[process.env.NODE_ENV];

P798 가맹점 정보 오류

존재하지 않는 가맹점 정보로 요청하거나, 서비스가 중지된 MID를 사용할 때 발생합니다.

해결 방법

• MID가 유효한지 영업 담당자에게 확인
• 가맹점 계약 상태 확인

9704 거래 내역 없음

가상계좌 강제 입금 처리 시, 해당 거래 건을 DB에서 찾지 못할 때 발생합니다.

해결 방법

• 개발 환경에서 테스트한 거래 건인지 확인
• 요청 거래 정보가 승인 당시와 동일한지 확인
• 환경(개발/운영)이 일치하는지 확인

8873 / 8373 미등록 가맹점 / 하위사업자몰 오류

해결 방법

• 다른 카드사로 결제 시도
• 여러 카드사에서 동일 오류 발생 시 영업팀에 문의

P520 빌키 중복 등록

정기결제용 빌키(Bill Key) 등록 시, 이미 등록된 회원번호와 중복될 때 발생합니다.

해결 방법

• 기존 빌키 삭제 후 재등록 (권장)
• 또는 서로 다른 custNo 사용

추가 도움말

위 내용으로 해결되지 않는 경우 아래 리소스를 참고해주세요.