파트너 수수료 계층별 요율 설정

수수료 계층 구조를 건드리는 작업은 항상 긴장된다. 금액이 직접 오가는 로직이라 버그 하나가 정산 이의로 바로 이어지기 때문이다. 이번에 파트너 수수료 세팅 스킬을 추가하면서 계층별 요율 모델을 정리한 과정을 써둔다.

차등 수수료 모델의 구조

우리가 쓰는 수수료 구조는 유통 계층별로 요율이 다르게 설정되는 차등 모델이다. 핵심은 하위 계층이 상위 계층보다 높은 요율을 부담하고, 그 차액이 상위 계층의 수익이 된다는 점이다. 단순하게 말하면 마진이 계층 간 스프레드로 만들어지는 구조다.

여기서 중요한 것은 계층 순서가 뒤집히면 마진이 음수가 된다는 점이다. 예를 들어 중간 계층 요율이 실수로 최하위보다 높게 설정되면, 중간 계층은 하위로부터 걷는 것보다 더 많이 내야 하는 상황이 생긴다. 이걸 런타임에서 걸러내지 않으면 정산 배치가 돌고 난 뒤에야 이상한 숫자가 나와서 추적이 훨씬 복잡해진다.

그래서 이번 작업에서 계층별 요율 순서가 맞는지 체크하는 validation을 추가했다. 설정 저장 시점에 "상위 계층 요율 < 하위 계층 요율" 조건을 명시적으로 검사하는 방식이다. 이런 류의 validation은 "당연히 지켜지겠지"라고 넘기기 쉬운데, 어드민 화면에서 실수로 값을 잘못 입력하는 경우가 꼭 생긴다.

수수료 계산 로직과 반올림 처리

수수료는 비율 수수료와 건당 고정 수수료를 합산한다. 코드로는 단순하다.

// 비율 수수료 + 건당 고정 수수료 합산
long feeAmount = (long)(txAmount * feeRate) + perTxFee;

(long) 캐스팅이 사실상 내림(floor) 처리를 한다. 이게 의도적인 선택인지 확인하는 게 이번 작업에서 신경 쓴 부분이었다. 원 단위 수수료 계산에서 반올림 방향은 작게 보여도 누적 정산 금액에서 차이가 생기고, 어느 쪽 방향이냐에 따라 수수료를 내는 파트너와 플랫폼 중 누가 유리해지는지가 달라진다.

일반적으로 수수료를 내는 쪽 관점에서 내림 처리가 분쟁을 줄인다. 0.5원을 올려서 1원으로 만들면 파트너 입장에서는 "왜 더 내냐"는 질문이 나온다. 내림이면 적어도 자기에게 불리한 방향은 아니기 때문에 이의가 적다. 반대로 플랫폼이 받는 입장이라면 올림을 쓰고 싶겠지만, 이걸 파트너 계약서에 명시하지 않으면 나중에 문제가 된다. 지금 구조는 내림으로 통일되어 있고, 그게 맞는 방향이라 판단했다.

계층별 요율이 소수점 둘째 자리까지 들어오는 구조라 double 연산 오차도 주의 포인트다. 금액이 커질수록 부동소수점 오차가 1원 단위에서 튈 수 있어서, 요율을 내부적으로 정수 단위(bp, basis point)로 관리하는 방식도 대안이 된다. 예를 들어 1.0%를 100bp로 저장하면 txAmount * bpRate / 10000으로 정수 연산만 쓸 수 있다. 이번에는 기존 방식을 유지했지만 금액 규모가 커지면 고려할 지점이다.

정산 배치 설계 원칙

정산 배치는 주기적으로 실행되면서 해당 기간 거래 내역을 집계하고 수수료를 확정한다. 여기서 멱등성이 핵심이다. 같은 기간을 두 번 실행했을 때 결과가 달라지면 안 된다.

멱등성을 지키기 위해 챙기는 것들을 정리하면:

• 배치 실행 전에 해당 기간이 이미 확정(locked) 상태인지 체크
• 확정된 기간에는 재계산 없이 기존 결과를 반환하거나 실행 자체를 스킵
• 배치 실행 로그에 실행 시각, 기간, 처리 건수, 총 수수료 합계를 기록해서 나중에 대조 가능하게 함
• 배치 도중 실패하면 부분 결과를 커밋하지 않고 전체 롤백

특히 마지막 항목이 중요하다. 중간에 실패한 배치가 일부 계층에만 수수료를 확정해두고 멈추면, 다음 실행 시 "이 기간은 이미 처리됨"으로 판단해서 나머지를 빠트리는 경우가 생길 수 있다. 기간 단위 lock 상태를 "전체 성공 후에만 확정"으로 관리하는 것이 기본이다.

작업 규모 자체는 크지 않았다. 스킬 추가와 validation 로직, 용어 정리가 전부였다. 그래도 수수료 계산은 건드릴 때마다 케이스를 하나씩 더 챙기게 된다. 이번에 계층 요율 순서 검증을 추가한 것처럼, 이런 방어 코드가 쌓이면서 정산 로직의 안정성이 올라간다고 생각한다.