23장 결제와 공통 서비스

계정·조직·결제·알림·전자문서·메시징은 여러 제품이 함께 쓰는 공통 서비스입니다. 공통인 것은 업무 의미와 계약이고, 실제로 실행하는 서버는 각 제품의 아키텍처가 고릅니다. 이 장은 결제와 외부 연동에서 지키는 공통 원칙을 설명하고, 무엇이 실제로 제공되는지를 구분해 적습니다.

왜 필요한가

여러 제품이 결제·구독, 세금계산서, 현금영수증, 사업자 상태 조회, 메시징을 함께 씁니다. 지침이 한 제품의 문서에만 있으면 다른 제품과 AI 에이전트가 계약을 찾지 못하고, 공급자(provider) API를 직접 부르는 코드가 다시 생깁니다.

돈과 법적 문서는 실수의 비용이 큽니다. 응답이 늦었다고 다른 공급자에게 다시 보내면 세금계산서가 두 번 발행될 수 있습니다. 검증하지 않은 결제 신호로 기능을 열면 실제로 결제되지 않은 이용을 허용하게 됩니다.

한때는 중앙 결제 서비스를 모든 제품의 필수 구조처럼 설명했습니다. 2026-10-01 KST에 이를 바로잡았습니다. 기능과 코드를 함께 쓰는 것과 중앙 서버 하나를 모두가 쓰는 것은 다른 문제입니다.

모델: 공통인 것과 고르는 것

text

회사 공통 정의·표준·가격 규칙 (Leysys Docs)
          │ 참조
제품별 업무·운영·아키텍처 (각 제품 Docs)
          │ 채택
제품 화면 / 제품 서버
          │ 인증된 업무 요청
승인된 실행 주체 ──> 공급자 adapter
          └──────> 검증된 결제 사실 / 제품 정책에 따른 이용 권한

실행 주체는 제품의 결정 기록이 고릅니다.

선택	제품이 채택하는 것	실행 주체가 맡는 것
중앙 Billing Authority	승인된 API·client, catalog·entitlement 계약	공급자 호출, 결제 장부, 대사, 정규화된 entitlement
제품 소유 결제 서버	그 제품 결정 기록의 결제·권한 API	공급자 호출, 결제 상태와 권한 전이, 대사, 감사
Integrations gateway	제공이 확인된 capability 계약	routing, 문서 binding, 같은 공급자 조회·대사

Billing Authority는 결제·구독·환불·공급자 처리와 entitlement 발급만 맡는 서비스입니다. 저장소 이름 leysys-control-plane은 호환을 위해 남긴 것이고, 범용 회사 플랫폼을 뜻하지 않습니다.

결제: 결제 사실과 이용 권한은 다른 상태입니다

공급자의 결제 성공은 외부 사실입니다. 기능을 여는 것은 그 사실을 검증한 뒤의 별도 상태 전이입니다.

text

공급자 결제 검증 → 로컬 결제 전이 확정 → catalog 부여 해석 → entitlement 전이 확정

금액·통화·판매 주체·공급자는 브라우저 입력이 아니라 서버가 정합니다. Billing Authority를 쓰는 제품은 승인된 가격 식별자(priceId)만 보내고 나머지는 서버의 판매 항목 목록(catalog)이 정합니다. 결제 뒤 돌아오는 주소는 이동 신호일 뿐이고, 제품은 상태를 다시 조회합니다.
이용 권한(entitlement)은 검증된 결제 사실에서 나온 결과로만 판단합니다. 결과가 없거나, 만료·정지됐거나, 검증할 수 없거나, 조회에 실패하고 승인된 짧은 캐시도 없으면 기능을 열지 않습니다(fail closed). Billing Authority를 쓰는 제품은 공급자 상태를 스스로 해석하지 않고, paid=true 같은 별도 정본도 만들지 않습니다.
Webhook(공급자가 보내는 알림)은 받기와 적용을 나눕니다. 원문을 저장하고, 이벤트 ID로 중복을 막고, 서명 검증이나 재조회로 사실을 확인한 뒤에만 상태를 바꿉니다. HTTP 200 응답과 업무 처리 완료는 같은 상태가 아닙니다.
결과가 불명확한 unknown은 성공이나 실패로 추측하지 않고, 같은 공급자에서 조회해 맞춥니다(대사, reconciliation).

외부 연동: 공급자 binding은 gateway가 소유합니다

세금계산서·현금영수증·사업자 상태 조회·메시징은 결제와 분리한 Integrations gateway가 다루도록 설계했습니다. 제공 상태는 아래 표에 있습니다. 제품은 「세금계산서 발행」 같은 기능(capability) 단위로 요청하고, 공급자 이름이나 공급자 전용 필드를 넣지 않습니다.

이미 발행한 문서는 처음 발행한 공급자에 영구히 묶입니다(binding). 취소도 그 공급자가 처리합니다.
공급자를 고르는 정책은 binding이 없는 새 문서에만 적용합니다.
결과가 불명확하면 같은 공급자로만 대사합니다. 다른 공급자에 다시 발행하지 않습니다.

결제와 나누는 이유는 넷입니다. 회계 문서는 결제와 다른 법적 상태를 갖습니다. 원문에 담긴 개인정보와 보존 기간이 다릅니다. 발행 결과가 불명확할 때 자동으로 다른 공급자로 넘기면 중복 발행 위험이 큽니다. 공급자 장애가 결제와 이용 권한 조회로 번지면 안 됩니다.

멱등 키

같은 요청이 두 번 와도 결과가 한 번만 생기게 하는 성질을 멱등성(idempotency)이라고 합니다. 데이터를 바꾸는 모든 요청은 두 키를 함께 씁니다.

키	소유	규칙
안정 업무 키(예: `documentKey`)	제품	같은 업무 문서에 영구히 재사용
`idempotencyKey`	제품의 요청	같은 의도의 재요청에 재사용

시간 초과가 났다고 새 키를 만들어 다시 보내면 중복 문서가 생길 수 있습니다. 같은 키로 기존 요청을 조회합니다.

가격 규칙 요약

요금 한 항목은 수량 × 단가이고, 합계는 그 합입니다. 기본료는 수량이 1인 항목입니다.
계산은 네 층입니다. ① 요금 규칙 → ② 가격 조정(할인·할증) → ③ 부가세 → ④ 결제와 정정. 층을 넘나드는 규칙을 만들지 않습니다.
옵션과 모듈은 요금 규칙을 더할 뿐, 이미 있는 규칙의 단가를 바꾸지 않습니다.
같은 수준의 조정은 합산하므로 적용 순서와 결과가 무관합니다. 끝수는 고객에게 유리하게 처리합니다.
결제수단에 따라 달라지는 할증은 만들지 않습니다. 여신전문금융업법은 카드 결제를 이유로 고객을 불리하게 대우하거나 가맹점수수료를 고객에게 부담시키는 것을 금지합니다.
정해지지 않은 단가는 0원이 아닙니다. 그런 견적은 보류합니다.
월 이용료와 따로 한 번 받는 비용(세팅비 · 인건비)은 견적서에서 「일회성 비용」 표로 따로 보이고, 월 금액과 월 할인 · 할증에 섞지 않습니다. 인건비는 「시간 단가」(시간당 금액 × 시간) 또는 「정액」(금액 하나)으로 적습니다.
가격은 조직 단위로 세지만, 청구서는 조직 하나로 받거나 워크스페이스마다 나눠 받을 수 있습니다.

제공 상태

다음은 2026-10-01 KST에 확인한 상태입니다. 서버가 실행 중이거나 SDK가 있다는 사실만으로 제품의 운영 채택을 입증하지 않습니다.

항목	확인된 상태	한계
Billing Authority	staging(운영 전 시험 환경) 실행 중	운영 채택과 실제 결제 거래는 미확인
`@leysys/control-plane-client`	`0.1.1` 배포 기록, 소비 코드 확인	운영 연결의 증거는 아님
리스팅 플랫폼 결제	플랫폼별 Supabase Edge Function 결제로 결정(2026-09-26 KST)	공통 reference kit 추출은 계획
Integrations gateway·client	2026-07-15 KST 기록 기준 로컬 기반 코드, SDK 미배포	현재 운영 여부 미검증
공통 가격 규칙	2026-09-22 KST 확정	확정 당시 프로토타입 계산기에서 요금 규칙과 단가 대체 구현만 확인

경계와 예외

결제·연동 상세 문서는 그 구현을 채택하거나 유지보수하는 사람을 위한 참고 계약입니다. 회사 전체에 대한 채택 명령이 아닙니다.
리스팅 플랫폼의 결정을 회사 전체의 Edge Function 의무나 Billing Authority 폐기로 넓히지 않습니다.
서비스 토큰과 공급자 비밀키는 승인된 실행 주체의 서버에만 둡니다. 브라우저 번들, 모바일 앱, VITE_* 같은 공개 환경변수에 넣지 않습니다.
계정 기능의 코드를 함께 써도 단독 브랜드의 가입·계정은 별도입니다(18장).
청구 업무를 맡길 사람의 역할은 22장의 청구 추가 역할을 씁니다.
금액과 상품별 정책은 각 가격표가 소유합니다.

정리

공통인 것은 업무 의미와 계약이고, 실행 주체는 제품 아키텍처가 고릅니다.
결제 사실과 이용 권한은 다른 상태이며, 검증된 사실 없이 기능을 열지 않습니다.
문서는 처음 발행한 공급자에 묶이고, 결과가 불명확하면 같은 공급자로만 대사합니다.
모든 변경 요청은 안정 업무 키와 멱등 키를 함께 씁니다.
계획·로컬·staging·운영을 구분해 적고, 출시되지 않은 것을 쓸 수 있다고 말하지 않습니다.

23장 결제와 공통 서비스 ​

왜 필요한가 ​

모델: 공통인 것과 고르는 것 ​

결제: 결제 사실과 이용 권한은 다른 상태입니다 ​

외부 연동: 공급자 binding은 gateway가 소유합니다 ​

멱등 키 ​

가격 규칙 요약 ​

제공 상태 ​

경계와 예외 ​

정리 ​

정본 ​