OpseerOpseer
Docs
Dashboard

Stripe

Stripe 계정을 연결해 일일 Net Revenue, 결제/환불, 활성 구독, MRR을 한 곳에서 추적하세요.

Last updated: 2026-05-18

Stripe 연동은 사용자가 발급한 Restricted API Key (read-only)를 통해 결제·구독 데이터를 조회합니다. 키는 AES-256-GCM으로 암호화되어 저장되며, sk_ 풀 권한 키는 거부됩니다.

사전 준비

  • Stripe 계정 (Live 또는 Test mode 모두 가능)
  • API Keys 발급 권한 (Owner / Developer 역할)
  • Starter / Plus / Max 플랜 (수익 알림은 유료 기능)

Restricted API Key 발급

1

Stripe API Keys 페이지 접속

dashboard.stripe.com/apikeys 로 이동합니다. 페이지 아래쪽 "Restricted keys" 섹션을 찾으세요 (Standard keys 아님).

2

Create restricted key

"+ Create restricted key" 버튼 클릭.

3

Third-party application 선택

"Providing this key to a third-party application" 옵션 선택.

4

애플리케이션 정보 입력

Name: Opseer / URL: https://opseer.com

5

권한 설정 — Permissions 컬럼만

Customize permissions 섹션에서 ⚠️ Permissions 컬럼만 사용. Connect permissions 컬럼은 모두 None 유지.

Read 체크할 권한 (12개)

Core 카테고리: Balance, Balance Transaction Source, Charges and Refunds, Customers, Disputes, Events, Payment Intents, Payouts, Products

Billing 카테고리: Invoices, Prices, Subscriptions

나머지 모든 항목과 Connect permissions 컬럼 전체는 None 유지. 위 12개만 Read 체크.

Events 권한은 MRR 추세 추적(Yesterday MRR 카드, MRR Waterfall 차트)에 필요합니다. 없으면 MRR 추세 차트가 채워지지 않지만, 일일 수익 데이터 수집은 정상 동작합니다.

Opseer에 키 등록

1

계정 페이지 또는 연동 페이지

/dashboard/account의 Stripe 카드, 또는 /dashboard/integrations의 계정 연동 영역에서 Connect 클릭.

2

키 입력

발급받은 Restricted API Key (rk_live_... 또는 rk_test_...)를 붙여넣고 Connect.

3

자동 검증

Opseer가 prefix 검증(sk_ 차단) + Stripe API에 dry-run 호출(balance retrieve)로 키 유효성을 확인합니다. 나머지 권한(Subscriptions 등)은 실제 데이터 조회 시 필요합니다. 통과하면 즉시 연결.

Stripe 연결은 프로젝트 단위가 아닌 계정 단위입니다. 한 번 연결하면 모든 프로젝트에서 사용 가능합니다.

수집되는 데이터

일별 시계열

balance_transactions를 일별로 그룹핑해 다음 메트릭을 산출합니다:

  • Net Revenue (결제 - 환불)
  • Charges (결제 건수)
  • Refunds (환불 건수 + 환불액)
  • Failed Payments (결제 실패 건수)
  • Disputes (분쟁 건수)

현재 시점 스냅샷

  • MRR (월 반복 매출, 활성 구독 합산)
  • Active Subscriptions (활성 구독 수)

MRR은 Stripe 정산 통화 기준으로 표시됩니다. 다른 통화(예: KRW, JPY)로 청구되는 구독은 Stripe 실제 결제 환율로 정산 통화에 환산되어 합산됩니다. 종량제(usage-based) 구독은 최근 청구액 기준으로 MRR 총액에 포함됩니다.

MRR 변화 추적 (일 1회 자동 수집)

Opseer는 하루 1회 Stripe 구독 이벤트를 폴링해 일별 MRR 변화량을 자동으로 추적합니다. 이 데이터가 Yesterday MRR 카드와 MRR Trend / MRR Waterfall 차트를 채웁니다.

  • New MRR — 신규 구독 생성
  • Expansion MRR — 업그레이드 (플랜 단가 상승)
  • Contraction MRR — 다운그레이드 (플랜 단가 하락)
  • Churned MRR — 해지 / 삭제
  • Net MRR Movement — 위 항목 합산
  • MRR Snapshot — 매일 누적 이월되는 MRR 합계

Stripe는 이벤트를 30일간 보관합니다. 최초 연결 시 최대 30일을 자동 backfill하며, 그 이전 이력은 조회 불가합니다. Restricted API Key에 Events 권한(Read)이 설정되어 있어야 합니다.

캐시 정책

페이지 진입 시 cache(90일 sliding window)만 read하며 API 호출은 하지 않습니다. Refresh 버튼 클릭 시 90일 전체를 재호출하여 cache를 교체합니다. revenue_daily_cache 테이블에 source=stripe 로 저장됩니다.

일일 알림

/dashboard/alert에서 Stripe 토글을 켜면 매일 "📊 Opseer Revenue Daily Report"에 어제 메트릭이 포함되어 발송됩니다. 결제 3채널(Stripe / RevenueCat / Polar)은 5 metric 통일 — MRR / Revenue / Orders / New Subs / Churned 동일 라벨·동일 순서로 표기됩니다.

보안

  • sk_ 시작 키는 입력 단계에서 거부 (rk_ 키만 허용)
  • AES-256-GCM 암호화 저장 (opseer_user_integration.config)
  • 복호화는 service_role 권한으로만 가능
  • 키 분실 시 Stripe Dashboard에서 즉시 Revoke 가능

문제 해결

"INVALID_PREFIX"

Standard keys (pk_ / sk_)를 입력했을 때 발생합니다. Restricted Key (rk_)만 허용됩니다.

"AUTH_FAILED"

키가 만료되었거나 balance 권한이 없습니다. 키 유효성은 balance retrieve로 확인되므로, 연결 성공 후에도 Subscriptions 등 다른 권한이 없으면 해당 데이터가 조회되지 않습니다. 위 12개 read 권한을 모두 체크했는지 확인 후 새 키를 발급해주세요.

MRR이 0으로 표시됨

Subscriptions 권한이 없거나 활성 구독이 없는 경우입니다. 권한을 다시 확인하세요.

Yesterday MRR이 "—"로 표시됨

MRR 수집 cron이 아직 실행되지 않았거나(하루 1회 실행), Restricted API Key에 Events 권한이 없는 경우입니다. Events → Read가 활성화되어 있는지 확인 후, 다음 일일 수집을 기다리거나 재연결(30일 backfill 자동 실행)하세요.

연결 해제

계정 또는 연동 페이지의 Stripe 카드에서 "연결 해제" 클릭. 암호화된 키와 캐시 데이터가 삭제됩니다. Stripe 계정 자체에는 영향이 없으며, 추가 보안을 위해 Stripe Dashboard에서도 해당 키를 Revoke하시는 것을 권장합니다.