상품권 PIN 충전 실패 원인 찾아 결제 응답 코드 체계 전면 교체

상품권 PIN 충전 흐름 손봄

오늘 결제대행사 쪽 상품권 PIN 충전 연동에서 실패율이 튀어서 한 번 갈아엎음. PIN 검증 응답 포맷이 V1.8 기준으로 바뀌었는데, 우리 쪽 컨트롤러가 옛날 스키마 그대로 파싱하고 있어서 정상 PIN도 invalid 처리됨.

증상

• PIN 입력 → 결제대행사 응답 200 인데 결과 코드 매핑 실패
• 파트너 잔액 충전 안 되고 "유효하지 않은 PIN" 토스트만 뜸
• 로그엔 NPE 없고 "unknown response code" warn 만 잔뜩

처음엔 단순 PIN 만료 의심함. 근데 영업쪽에서 "방금 발급된 PIN인데 안 된다"는 제보 받고 응답 raw 까봤더니 코드 체계 자체가 달랐음.

숫자 코드에서 enum 문자열로 바뀜. 변경 공지 메일은 왔었는데 다른 팀이 받고 우리한테 안 넘어옴. 매번 이런 식.

손본 부분

응답 매핑 메서드랑 충전 내역 쿼리 둘 다 손댐.

// 기존: 숫자 코드 직접 비교
if ("0000".equals(resp.getCode())) { ... }

// 수정: enum 매핑 + 미정의 코드 fallback
ResultCode code = ResultCode.from(resp.getCode());
if (code.isSuccess()) { ... }

SQL 쪽이 더 골치 아팠음. 충전 내역 테이블에 result_code 컬럼이 varchar(4) 로 박혀 있어서 enum 문자열이 그냥 잘림. EXPIRED 가 EXPI 로 들어가서 통계 다 깨짐. 컬럼 길이 늘리고, 이미 유입된 잘린 데이터는 케이스별로 백필함.

• varchar(4) → varchar(20) 로 변경
• 잘린 값 → 원래 enum 으로 일괄 update
• 외부 응답을 컬럼에 직접 넣지 말고 내부 enum 거쳐서 정규화

회고

1. 외부 결제대행사 응답을 raw 그대로 DB에 박아넣는 건 진짜 위험함. 정규화 레이어 한 겹 거쳐야 됨. 코드 체계 바뀌면 그대로 깨짐.
2. 변경 공지 메일 라우팅 파편화는 매번 발목 잡음. 받는 그룹 정리하고 슬랙 채널로 미러링하기로 함.
3. varchar(4) 는 7~8년 전 누군가의 결정이었고 그때는 숫자 코드였으니 합리적이었지만 지금은 부채. enum 가능한 최대 길이 + 여유 두는 게 맞음.
4. 외부 API 의 응답 코드 체계는 우리 도메인 enum 으로 한 번 깎아서 들이는 패턴, 이번 기회에 다른 연동 모듈에도 전부 깔기로 함.

다음