오픈소스 웹훅 없는 결제 프로세서 Flowglad

 (github.com/flowglad)
2P by GN⁺ | ★ favorite | 댓글 1개
  • Flowglad는 웹훅 없이 작동하는 오픈소스 결제 처리 플랫폼으로, 개발자가 최소한의 코드로 청구·결제 기능을 통합할 수 있는 구조
  • Stateless 아키텍처를 통해 subscriptions 테이블이나 customer_id 관리 없이 자체 사용자 ID로 결제 상태를 조회 가능
  • Full-Stack SDK를 제공해 백엔드에서는 flowgladServer.getBilling(), 프론트엔드에서는 useBilling() 훅으로 고객 상태를 실시간 반영
  • 테스트 모드에서 가격 모델을 실험하고 클릭 한 번으로 프로덕션에 반영할 수 있으며, 앱 재배포 없이 요금제 전환 가능
  • 결제 통합의 복잡성과 비용을 줄여 개발자 경험(DX) 을 개선하고, 다양한 결제 제공자와의 연결을 단일 통합으로 확장하는 기반 제공

주요 기능

  • Stateless 구조로 웹훅, 구독 테이블, 고객 ID, 환경 변수 관리가 불필요
    • 가격과 기능 매핑을 수동으로 관리할 필요 없이 Flowglad에서 직접 처리
  • 단일 진실 소스(Single Source of Truth) 로 고객의 최신 청구 상태, 기능 접근 권한, 사용량 크레딧을 조회 가능
  • 사용자 정의 ID 기반 접근을 지원해 기존 인증 시스템의 사용자·조직 ID로 고객 상태를 조회
  • Full-Stack SDK 제공
    • 백엔드에서 flowgladServer.getBilling() 호출
    • React 프론트엔드에서 useBilling() 훅으로 실시간 결제 상태 반영
  • 유연한 가격 모델 관리
    • 테스트 모드에서 새로운 요금제를 실험하고 클릭 한 번으로 프로덕션 반영
    • 앱 재배포 없이 요금제 회전 가능

설치 및 통합

  • 프로젝트 유형에 따라 @flowglad/nextjs, @flowglad/react, @flowglad/express, @flowglad/server 패키지를 설치
  • Next.js 통합 예시
    • FlowgladServer 인스턴스를 생성해 자체 고객 ID를 전달
    • API 라우트에서 nextRouteHandler를 사용해 Flowglad와 안전하게 통신
    • 루트 레이아웃에 FlowgladProvider를 추가해 프론트엔드에서 결제 상태 자동 로드
  • B2C는 user.id, B2B는 organization.id 또는 team.id를 고객 ID로 사용
  • Flowglad는 별도의 고객 ID 관리나 인증 시스템 변경을 요구하지 않음

프론트엔드 예시

  • useBilling() 훅으로 기능 접근 여부(checkFeatureAccess)와 사용량(checkUsageBalance) 확인
  • 기능 접근이 제한된 경우 업그레이드 안내 메시지 표시
  • 사용량이 부족할 경우 createCheckoutSession으로 결제 세션 생성

백엔드 예시

  • flowglad(user.id).getBilling()으로 서버 측에서 기능 접근 및 사용량 확인
    • 예: fast_generations 기능 접근 여부 확인 후 처리 분기
    • 예: chat_messages 사용량 크레딧 부족 시 오류 발생

시작하기

  • 대시보드에서 템플릿을 이용해 가격 모델 생성
  • 제공 템플릿 유형
    • 사용량 제한 + 구독 하이브리드 (Cursor 유사)
    • 무제한 사용 (ChatGPT 소비자형)
    • 계층형 접근 + 사용 크레딧 (Midjourney 유사)
    • 기능 잠금형 구독 (Linear 유사)
  • 필요 시 템플릿 없이 직접 모델 생성 가능

기술 스택

  • Next.js, tRPC, React.js, Tailwind CSS, Drizzle ORM, Zod, Trigger.dev, Supabase, Better Auth 기반

프로젝트 목표

  • 지난 15년간 개발 스택은 다양해졌지만 결제 영역의 혁신은 거의 없었음
  • 대부분의 결제 서비스는 계정 설정조차 영업팀을 거쳐야 하며, 셀프서비스 결제 옵션이 부족
  • 그 결과 결제 관련 개발자 경험(DX) 과 비용 개선이 정체 상태
  • Flowglad는 결제 통합과 유지보수 시간을 최소화하고, 단일 통합으로 여러 결제 제공자 활용을 목표로 함
  • AI 확산으로 복잡해지는 스타트업 청구 환경 속에서 개발자 친화적 결제 레이어 구축을 지향

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견

  • 나는 왜 이것을 A) ‘payment processor’ 라고 부르는지 이해가 잘 안 됨
    실제로 결제를 직접 처리하지 않으면서 그렇게 부르는 게 이상하게 느껴짐
    또 B) ‘open source’라고 하지만, 모든 게 SaaS를 통해 돌아가고 데이터도 그들의 DB에 저장되는 것 같음
    기능 게이트, 사용 크레딧, 결제 스킴 같은 유연한 시스템을 만들려 애쓰고 있어서 문제의식은 공감하지만, 제목에서 약속한 만큼의 실질적인 제공은 느껴지지 않음

    • 공감해줘서 고맙고, 더 잘 해결할 수 있는 방법에 대한 의견을 듣고 싶음
      오픈소스 관련해서는 SaaS 부분은 AGPLv3, 나머지는 MIT 라이선스임
      ‘processor’라는 표현은 우리가 Stripe Connect를 통해 결제를 처리하더라도, 단순한 청구 SaaS가 아니라 결제 처리까지 포함한다는 점을 명확히 하고 싶었음
      예를 들어, 우리는 상점과 함께 chargeback 문제를 걱정함. Stripe 키만 가져다 쓰는 SaaS와 달리, 우리의 구조에서는 chargeback이 Stripe처럼 우리에게도 직접적인 이슈가 됨
    • 라이선스 파일에는 MIT와 AGPL 두 가지가 명시되어 있음

  • 이 제품이 몇 가지를 쉽게 만들어주는 건 맞지만, 실제로 더 나은지는 모르겠음
    고객의 구독 상태 같은 걸 확인할 때마다 Flowglad 서버로 API 요청을 보내야 하는 구조라면, 반응성이 떨어질 수 있음
    자주 접근하는 데이터는 캐시할 수 있겠지만, 그러면 이 레이어의 의미가 줄어듦
    Stripe 통합이 까다롭긴 하지만, 로컬에 아무것도 저장하지 않을 거라면 그냥 Stripe API를 직접 쓰는 게 낫다고 생각함
    나는 DB에 캐시된 상태를 두는 게 훨씬 편했음 — 복잡한 쿼리도 바로 날릴 수 있으니까
    이 구조에서는 Flowglad가 필요한 API를 제공하길 바라야 하고, 그렇지 않으면 고객 수만큼 API 요청을 날려야 할 수도 있음

    • 맞는 말임
      우리는 상점 쪽에 더 많은 데이터를 저장할 수 있게 하면서도, 우리가 다듬은 데이터 모델과 SDK의 사용성을 그대로 활용할 수 있도록 할 계획임
      Stripe API를 직접 쓰더라도 price id, plan, feature, customer id 매핑을 직접 관리해야 하는데, 이런 반복 작업을 없애고 싶음
      Stripe는 쓰기 중심 시스템이라 실시간 읽기 레이어로 쓰는 걸 권장하지 않음 (Stripe rate limits 문서)
      우리는 Shopify가 DTC 브랜드에 제공했던 것처럼, 개발자에게 통합된 결제 + 가치 이동 경험을 주는 걸 목표로 하고 있음

  • 처음에는 오해했는데, SDK와 코드만 오픈소스고 실제 청구 데이터는 Flowglad 서버로 전송되는 구조라서 데이터를 직접 소유하지 못하는 것 같음

    • 맞음, 제목이 여러 면에서 오해를 불러일으키는 표현임

  • 베타 출시 축하함!
    나도 비슷한 문제를 겪어서, Flowgrad와 비슷한 DX를 가진 Stripe 통합 라이브러리를 만들었음 (기능은 덜 풍부하지만)
    왜 만들었는지에 대한 블로그 글도 있음
    주요 차이는 최종 청구 정보 저장 위치임 — 우리는 DB 스키마와 웹훅 핸들러를 함께 제공해서 로컬 DB에 기록함
    혹시 도움이 될까 해서, 우리가 만든 MIT 오픈소스 라이브러리도 추천함

  • 베타 출시 축하함, 인상적인 제품이라 통합을 고려 중임
    그런데 왜 React 의존성이 필요한지 궁금함
    React 없이도 원하는 UI를 구현할 방법은 없었는지?
    우리는 Svelte 기반이라 이런 라이브러리 때문에 React를 끌어와야 하는 게 불편함

    • 좋은 지적임
      React로 시작한 이유는 우리가 가장 익숙했고 커뮤니티도 그쪽에 있었기 때문임
      React에 집착하는 건 아니고, Svelte와 Vue 지원도 곧 추가할 예정임
      데이터 모델과 플로우가 안정되면 다른 프레임워크로 SDK를 포팅할 계획임
    • Svelte를 선택했다면 이런 상황은 자주 겪게 될 것임
      React 사용자층이 10~50배는 크니까 이런 불편은 피하기 어려움
      하지만 React는 프레임워크가 아니라 컴포넌트 렌더링 레이어라, 잘 캡슐화된 외부 라이브러리라면 Svelte 안에서도 문제없이 쓸 수 있음

  • 랜딩 페이지 디자인이 정말 아름답게 만들어졌음
    부정적으로 보이고 싶진 않았고, 단지 Stripe 위에 구축된 게 아쉬웠음

    • 나도 마음에 들었음, zed.dev를 떠올리게 함
    • 고마움! 사실 사이트는 일부러 단일 페이지로 유지했음
      지난 1년을 청구 엔진, 데이터 모델, SDK 개발에 쏟았기 때문임

  • webhook이 인기 있는 이유는 단순하고 신뢰할 수 있으며 잘 작동하기 때문임
    하지만 이걸 쓰면 사용량, 구독 티어, 취소 등을 추적하기 위한 별도의 인프라를 구축해야 할 수도 있음

    • webhook은 비동기 작업이나 이벤트 기반 도메인에는 적합하지만, 결제나 권한 부여 같은 영역에는 최선의 모델이 아닐 수도 있음
      이상적인 세상에서는 돈이 오가면 그에 따라 고객이 접근할 수 있는 기능이 자동으로 정해지는 구조여야 함
      Shopify 같은 곳이 그런 예임 — webhook은 있지만 핵심 통합 포인트는 아님
      결제 webhook은 본래 복잡한 도메인 모델링 문제를 우회하기 위한 해킹적 해결책이었음

  • 이미 GNU Taler라는 프로젝트가 존재하며, 진짜 전문가들이 만든 시스템임
    https://www.taler.net/en/
    개인정보 보호 중심의 온라인 결제, 등록 없는 결제, 사기 방지 설계, 자체 인프라 운영 가능, 자유 소프트웨어라는 점이 특징임

  • 상점의 은행 계좌와 관련해서는 어떻게 작동하는지 궁금함
    이 저장소 외에 다른 게 필요한가?

    • 맞음, 아직 acquiring bank 파트너십을 자체 호스팅하는 방법은 없음
      현재는 Stripe Connect를 통해 상점 계정을 설정함
      Stripe가 상점 결제를 지원하는 국가의 법인이라면 바로 사용할 수 있음
      장기적으로는 결제 쪽에 더 깊이 통합될 계획임
    • 여전히 결제 제공자나 상점 계정이 필요함
      구조적으로는 다른 게이트웨이 서비스와 비슷하지만, 중간 수수료가 추가되므로 거래당 비용이 더 높아질 수 있음

  • Stripe의 webhook 이벤트가 250개 이상이라 복잡하다고 했는데, 모든 이벤트를 다 들을 필요는 없음

    • 하지만 어떤 이벤트가 내 앱의 비즈니스 라이프사이클에 중요한지 직접 판단해야 함
      예를 들어 charge.succeeded, payment_intent.succeeded, customer.subscription.created를 각각 어떻게 처리하고 중복을 피할지 고민해야 함
      이런 세부 지식이 많아야 Stripe를 제대로 통합할 수 있음
    • Stripe는 UI부터 API까지 기능이 과도하게 확장되어 있음
      10년 전에는 20분 만에 통합했는데, 최근에는 하루 종일 걸렸음
답변달기