결제 PG의 원가 설정값 정정

결제 게이트웨이 통합에서 원가와 사용자 수수료를 혼동하는 버그를 발견해서 수정했다. 한 PG사(jeju)의 설정 테이블에서 pgCost(PG에게 우리가 지불하는 원가)가 사용자 수수료로 잘못 입력되고 있었다. 문서, Java 코드, SQL 초기화 스크립트까지 세 곳을 동시에 정정해서 설정값의 일관성을 맞췄다.

PG 비용 체계의 구조

대부분의 이커머스 결제 시스템에서 PG 관련 비용은 적어도 두 가지로 나뉜다:

• PG 원가(pgCost): PG 사업자에게 매 거래마다 지불하는 실제 수수료. 예를 들어 결제액의 2.5% 같은 것
• 사용자 수수료: 플랫폼이 최종 사용자(또는 판매자)에게 청구하는 요금. 이는 PG 원가뿐만 아니라 플랫폼의 이윤, 운영 비용 등을 포함해서 책정된다

이 둘은 전혀 다른 개념인데, 설정 테이블에서 애매하게 섞여 있었다. 그래서 결제 정산 로직에서 비용을 계산할 때 혼란이 생길 수 있는 상황이었다.

버그의 원인

변경 대상 파일들을 보면 문제의 규모가 드러난다:

특히 SQL 초기화 스크립트는 새로운 개발 환경이나 스테이징 환경을 구성할 때 자동으로 실행되므로, 이 잘못된 설정이 계속 퍼지고 있었다.

수정의 핵심

각 파일을 다음과 같이 정정했다:

// Before (잘못된 이해)
// pgCost = 사용자에게 청구하는 수수료

// After (올바른 이해)
// pgCost = PG 사업자에게 지불하는 원가
// userFee = 사용자에게 청구하는 수수료

// 예: 사용자가 10,000원을 결제하면
int baseCost = 10000;
int pgCost = (int)(baseCost * 0.025); // PG 원가: 250원 (2.5%)
int platformFee = (int)(baseCost * 0.10); // 사용자 수수료: 1,000원 (10%)

• 문서: jeju-kp-pay-integration.md에서 pgCost의 정의와 용도를 명확히 기술했다. "PG 사업자에게 지불하는 원가"라고 명시
• Java 코드: 비용 계산 로직에서 pgCost를 원가로, 별도 필드를 사용자 수수료로 처리하도록 수정
• SQL: INSERT_jeju_kp_pay_pg_config.sql에서 pgCost 값을 실제 PG 원가 수준(예: 2~3%)으로 정정

이런 버그가 왜 발생했나

몇 가지 원인을 생각해 본다:

1. 필드명의 모호성: pgCost라는 이름 자체가 "PG와 관련된 비용"이라고만 해석되고, 구체적으로 "원가"인지 "수수료"인지 불분명했다. 더 명확한 이름으로 pgAcquisitionCost 같은 걸 썼으면 혼동이 적었을 텐데.

2. 문서의 부재: 통합 초기에 담당자들 사이에서만 구두로 "이 필드는 원가"라고 알았던 것 같은데, 시간이 지나고 인수인계 과정에서 정확한 정의가 손실되었다.

3. 테스트의 한계: 단위 테스트나 통합 테스트에서 PG 원가와 사용자 수수료를 검증하는 케이스가 명시적이지 않아서, 정산 시스템이 실제 운영 데이터와 맞지 않아도 미리 발견하기 어려웠을 가능성.

같은 실수 피하기

비슷한 상황에서 배운 팀 차원의 주의점:

• 필드 네이밍 리뷰: 금액, 비용, 요금 관련 필드는 코드 리뷰 때 특히 엄격하게. "비용"이 아니라 "PG 원가 비용" 같이 명시적으로.
• 문서 우선성: DB 스키마 변경이나 새로운 외부 연동(PG 통합)은 먼저 문서로 정의하고, 그 다음 코드를 작성. 문서가 단일 진실 공급원이 되도록.
• 설정 초기화 스크립트의 일관성: SQL 초기화 스크립트는 개발 환경뿐만 아니라 실서비스 스키마 마이그레이션과도 맞아야 한다. 초기 데이터가 실제 운영 값을 반영하는지 DBA와 함께 검증하는 단계.

이번 수정이 향후 정산 로직을 명확하게 하고, 새로운 PG사 통합할 때 참고 모델이 될 수 있길 바란다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.