📖 결제 연동 가이드

💡 이 가이드는 게임 등록 시 필요한 결제 검증 정보를 설정하는 방법을 안내합니다.

📱 Google Play 연동 가이드

Google Play 인앱 결제 연동을 위한 단계별 가이드입니다.

✅ 1️⃣ 단건 인앱결제 (일회성)

코인, 포인트, 아이템 구매 등 일회성 결제

✅ Webhook 불필요

purchaseToken만으로 검증이 완료됩니다. 실시간 알림이 필요 없습니다.

필요한 정보:

  • productId - 상품 ID
  • purchaseToken - 구글 결제 고유 토큰

검증 API:

GET https://www.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{purchaseToken}

응답에서 "purchaseState": 0이면 결제 성공

✅ 2️⃣ 구독형 상품 (자동 결제)

월 정액, 프리미엄 멤버십 등 반복 결제

⚠️ Webhook 필수

구독은 자동으로 갱신/취소되므로, 스토어에서 직접 알림을 받아야 합니다.

Webhook이 필요한 이유:

  • 유저가 앱을 열지 않아도 결제 상태가 변경됨
  • 갱신, 취소, 환불, 만료 등의 이벤트 자동 처리
  • Google Play의 RTDN (Real-Time Developer Notifications) 필요

📊 요약

결제 유형Webhook검증 방법
단건 결제❌ 불필요purchaseToken으로 API 검증
구독 결제✅ 필수초기 검증 + Webhook 처리

🔗 Webhook 서버 구현 가이드 (구독 상품용)

Webhook은 구독형 상품을 사용할 때만 필요합니다. 단건 결제만 사용한다면 건너뛰어도 됩니다.

📍 구현 요구사항:

  • HTTPS 프로토콜 필수 (SSL 인증서 필요)
  • HTTP POST 메소드 지원
  • JSON 형식 데이터 파싱
  • 서명 검증 (보안을 위해 필수)
  • 빠른 응답 (200 OK, 30초 이내)
  • 멱등성 처리 (중복 알림 대응)

💡 개발 팁:

  • 로컬 개발 시 ngrok 등의 터널링 서비스 활용
  • Webhook 이벤트 로그를 남겨 디버깅에 활용
  • 재시도 로직 구현 (네트워크 오류 대응)
  • 테스트 환경용 Sandbox URL 별도 설정 권장

플랫폼에 전달해야 하는 값

결제 검증과 정산을 위해 아래 값을 전송하세요.

POST /api/payment/verify
{
  "paymentId": "결제 레코드 ID",
  "transactionId": "스토어 트랜잭션 ID",
  "paymentType": "google | apple"
}

사전 단계로 아래 결제 생성이 필요합니다.

INSERT payments (user_id, game_id, streamer_code, amount, verified=false)
→ 이후 /api/payment/verify 호출 시 verified=true 로 갱신되고 settlements가 자동 생성됩니다.

스트리머 추천 코드와 유저정보 전달

  • 유저가 스트리머 링크로 유입되면, 클라이언트에서 `streamer_code`를 저장
  • 결제 발생 시 `payments.streamer_code`에 함께 기록
  • 유저 식별자(user_id)는 Supabase `auth.users.id` 또는 자체 UID를 사용

스토어 수수료(Apple/Google) 이후 정산 방식

Apple/Google 인앱결제는 스토어 수수료가 먼저 차감됩니다. 이후 순매출(NetRevenue)을 기준으로 스트리머/플랫폼/개발사 분배를 수행합니다.

계산식

NetRevenue = 결제금액 × (1 - 스토어수수료율)
Streamer = NetRevenue × 스트리머율
Platform = NetRevenue × 플랫폼율
Developer = NetRevenue - Streamer - Platform

예시: 결제금액 100,000원

(1) 대형사 시나리오: 스토어 수수료 30%

NetRevenue = 100,000 × 0.7 = 70,000
Streamer = 70,000 × 0.10 = 7,000
Platform = 70,000 × 0.10 = 7,000
Developer = 70,000 - 7,000 - 7,000 = 56,000

(2) 중소사 시나리오: 스토어 수수료 15%

NetRevenue = 100,000 × 0.85 = 85,000
Streamer = 85,000 × 0.05 = 4,250
Platform = 85,000 × 0.10 = 8,500
Developer = 85,000 - 4,250 - 8,500 = 72,250

위 비율(스트리머 5%, 플랫폼 10%)은 예시입니다. 서비스 정책에 따라 비율을 조정할 수 있습니다.

참고: 현재 MVP 기본 정산 트리거는 총액 기준 스트리머 5% / 플랫폼 10% / 개발사 85%로 설정되어 있습니다. 스토어 수수료 이후 정산(넷기준)으로 변경하거나 비율을 수정하려면 데이터베이스 트리거 로직을 정책에 맞게 조정하세요.