자금이체 계좌 역할 명명

상태: 참고 규칙 — 신규 API·DB 계약을 확정할 때 검토합니다.

적용 대상: 수납, 송금, 환불, 가상계좌를 설명하는 문서와 모델

자금 흐름의 방향과 개별 계좌의 역할은 서로 다른 축입니다. Pay-in / Pay-out은 Leyve가 처리하는 업무 흐름의 방향을, Source / Destination은 한 번의 이체에서 돈이 나가고 들어가는 계좌의 역할을 가리킵니다.

역할 구분

용어	한글 설명	사용 기준
Pay-in	수취·수납 흐름	외부 자금이 Leyve가 관리하는 수납 흐름으로 들어옵니다.
Pay-out	송금·지급 흐름	Leyve가 관리하는 자금이 외부 수취자에게 나갑니다.
Source Account	출금 계좌	해당 이체에서 돈이 빠져나가는 실제 계좌입니다.
Destination Account	입금 계좌	해당 이체에서 돈이 들어가는 실제 계좌입니다.
Pay-in Virtual Account	수납용 가상계좌	납부자 또는 계약에 배정해 입금 식별에 사용하는 가상계좌입니다.

Pay-in / Pay-out은 프로세스 관점이고 Source / Destination은 단일 이체 관점이므로 서로 바꿔 쓰지 않습니다. 예를 들어 수납 이체에서는 납부자의 계좌가 Source Account, 수납용 계좌 또는 가상계좌가 목적지입니다. 환불·지급 이체에서는 고객의 수취 계좌가 Destination Account입니다.

계좌 필드

계좌 역할을 모델로 표현할 때는 다음 세 필드를 한 묶음으로 취급합니다.

suffix	의미	주의
Bank	은행 또는 금융기관	표시명과 기관 코드를 구분해야 하면 별도 필드로 나눕니다.
Number	계좌번호	화면·로그·분석 데이터에서는 필요한 범위만 마스킹합니다.
Holder	예금주	은행명과 다른 값입니다. 검증 여부가 필요하면 별도 상태를 둡니다.

예시:

payinVirtualAccountBank
payinVirtualAccountNumber
payinVirtualAccountHolder

sourceAccountBank
sourceAccountNumber
sourceAccountHolder

destinationAccountBank
destinationAccountNumber
destinationAccountHolder

피해야 할 모호한 이름

• Pay-in Account, Pay-out Account만으로는 실제 계좌가 출금원인지 입금처인지 불분명합니다. API·DB에서는 Source Account, Destination Account, Pay-in Virtual Account처럼 역할을 드러냅니다.
• 방향 기준을 문서마다 고객, Leyve, 금융기관 중 하나로 바꾸지 않습니다. Pay-in / Pay-out의 기준점은 Leyve가 관리하는 자금 흐름입니다.
• Bank, Number, Holder 가운데 하나를 다른 의미로 재사용하지 않습니다.

적용 범위

이 문서는 신규 모델과 문서의 명명 기준입니다. 현재 Prototype에 존재하는 필드를 일괄 변경하거나 금융기관별 API 필드명을 그대로 대체하라는 마이그레이션 지시는 아닙니다. 외부 연동에서는 제공자 필드를 이 역할 모델에 명시적으로 매핑합니다.

보존 배경

2025-05-17 작성된 삭제 예정 블로그의 fin 정보 메모에서 수납용 가상계좌와 Pay-in / Pay-out, Source / Destination 구분을 선별해 정리했습니다. 원문의 중복·오기는 제외했고, 현재 Prototype에서 사용하는 PayinVirtualAccount, SourceAccount, DestinationAccount 필드와 대조했습니다.