# v2: Stripe 계정 설정 및 API 키 발급

## Stripe란?

Stripe는 전 세계에서 가장 많이 사용되는 온라인 결제 플랫폼 중 하나입니다. 강력한 API와 개발자 친화적인 도구를 제공하여, 복잡한 결제 시스템을 쉽게 구축할 수 있습니다.

### Stripe의 장점

- **개발자 친화적**: 잘 설계된 RESTful API
- **문서화**: 상세하고 명확한 문서
- **Sandbox 모드**: 실제 돈을 쓰지 않고 테스트 가능
- **다양한 결제 수단**: 카드, 은행 이체, 모바일 결제 등
- **글로벌 지원**: 135개 이상의 통화 지원

## Stripe 계정 생성

### 1. 회원가입

1. https://stripe.com 방문
2. 우측 상단의 "Sign up" 클릭
3. 이메일 주소 입력
4. 비밀번호 설정
5. 이름과 국가 선택

### 2. 계정 유형 선택

Stripe는 두 가지 모드를 제공합니다:

#### Test Mode (테스트 모드)
- 실제 돈이 이동하지 않음
- 개발 및 테스트용
- 테스트 카드 번호 사용
- **이번 프로젝트에서 사용할 모드**

#### Live Mode (라이브 모드)
- 실제 결제 처리
- 비즈니스 정보 등록 필요
- 실제 카드 정보 사용

**중요**: 이 프로젝트에서는 반드시 **Test Mode**만 사용합니다!

## Stripe Dashboard 둘러보기

계정 생성 후 Dashboard에 접속하면 다음과 같은 메뉴를 볼 수 있습니다:

### 주요 메뉴

**Home**
- 매출 개요
- 최근 결제 내역
- 빠른 링크

**Payments**
- 모든 결제 내역
- 환불 관리
- 결제 상태 확인

**Customers**
- 고객 목록
- 고객별 결제 이력

**Products**
- 상품/서비스 관리
- 가격 설정

**Developers**
- **API keys** (가장 중요!)
- Webhooks
- Logs
- API 문서

## API 키 발급

API 키는 Stripe API에 접근하기 위한 인증 정보입니다.

### API 키 위치

1. Dashboard 좌측 메뉴에서 "Developers" 클릭
2. "API keys" 탭 선택
3. 우측 상단에서 **"Test mode" 토글이 켜져 있는지 확인** (중요!)

### API 키 종류

Stripe는 두 가지 종류의 API 키를 제공합니다:

#### 1. Publishable Key (공개 키)
```
pk_test_51Abc...xyz
```

- **용도**: 클라이언트 측(브라우저)에서 사용
- **공개 가능**: GitHub에 올려도 상대적으로 안전
- **권한**: 제한적 (토큰 생성 등만 가능)
- **예시**: 결제 폼에서 카드 정보 토큰화

#### 2. Secret Key (비밀 키)
```
sk_test_51Abc...xyz
```

- **용도**: 서버 측에서 사용
- **절대 공개 금지**: GitHub, 클라이언트 코드에 노출 금지
- **권한**: 모든 API 작업 가능
- **예시**: 결제 생성, 환불, 고객 정보 조회 등

**이번 프로젝트에서는 Secret Key만 사용합니다** (서버 사이드 프로젝트)

### API 키 복사하기

1. "Secret key" 섹션에서 "Reveal test key" 클릭
2. `sk_test_`로 시작하는 키를 복사
3. 안전한 곳에 임시 저장 (메모장 등)

**주의**: API 키가 노출되면 즉시 Dashboard에서 재생성해야 합니다!

## 테스트 카드 정보

Stripe는 Test Mode에서 사용할 수 있는 다양한 테스트 카드를 제공합니다.

### 기본 테스트 카드

```
카드 번호: 4242 4242 4242 4242
만료일: 미래의 아무 날짜 (예: 12/34)
CVC: 아무 3자리 숫자 (예: 123)
우편번호: 아무 번호 (예: 12345)
```

이 카드는 **항상 성공**합니다.

### 특수 시나리오 테스트 카드

결제 실패 테스트:
```
4000 0000 0000 0002  # 카드 거부
4000 0000 0000 9995  # 잔액 부족
```

3D Secure 인증 테스트:
```
4000 0027 6000 3184  # 3D Secure 인증 필요
```

더 많은 테스트 카드: https://stripe.com/docs/testing

## 보안 모범 사례

### 1. API 키 관리

**절대 하지 말아야 할 것**:
```typescript
// ❌ 나쁜 예: 코드에 하드코딩
const stripe = new Stripe('sk_test_abc123...');
```

**올바른 방법**:
```typescript
// ✅ 좋은 예: 환경 변수 사용
import 'dotenv/config';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
```

### 2. .gitignore 설정

프로젝트 루트에 `.gitignore` 파일 생성:

```
# 환경 변수 파일
.env
.env.local
.env.*.local

# 의존성
node_modules/

# 빌드 결과
dist/
build/

# IDE 설정
.vscode/
.idea/
```

### 3. 환경 변수 예시 파일

`.env.example` 파일 생성 (GitHub에 커밋 가능):

```
# Stripe API Keys (Test Mode)
STRIPE_SECRET_KEY=sk_test_your_key_here
STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here

# OpenAI API Key
OPENAI_API_KEY=sk-your_openai_key_here
```

실제 사용할 `.env` 파일:

```
STRIPE_SECRET_KEY=sk_test_51Abc...xyz
STRIPE_PUBLISHABLE_KEY=pk_test_51Abc...xyz
OPENAI_API_KEY=sk-proj-...
```

### 4. 키 노출 시 대처법

만약 API 키가 실수로 GitHub에 올라갔다면:

1. **즉시 Stripe Dashboard에서 키 삭제**
   - Developers > API keys > 해당 키 옆의 "..." 클릭 > "Roll key"
2. **Git 히스토리에서도 제거**
   ```bash
   git filter-branch --force --index-filter \
     "git rm --cached --ignore-unmatch .env" \
     --prune-empty --tag-name-filter cat -- --all
   ```
3. **새로운 키 발급 및 설정**

## Stripe Webhook (선택사항)

Webhook은 Stripe에서 특정 이벤트가 발생했을 때 서버로 알림을 보내는 기능입니다.

### 주요 이벤트

- `payment_intent.succeeded`: 결제 성공
- `payment_intent.payment_failed`: 결제 실패
- `customer.created`: 고객 생성
- `charge.refunded`: 환불 처리

### 이번 프로젝트에서는?

이번 프로젝트는 **직접 API를 호출**하여 데이터를 조회하므로 Webhook은 사용하지 않습니다. 하지만 실제 프로덕션 환경에서는 Webhook을 사용하는 것이 좋습니다.

## Dashboard 활용 팁

### 1. Logs 확인

`Developers > Logs`에서 모든 API 요청을 확인할 수 있습니다:
- 요청 시간
- 엔드포인트
- 응답 상태
- 요청/응답 내용

디버깅할 때 매우 유용합니다!

### 2. Test Clocks (시간 여행!)

`Developers > Test clocks`를 사용하면 시간을 조작할 수 있습니다:
- 구독 갱신 테스트
- 무료 체험 기간 종료 테스트
- 지연된 결제 테스트

### 3. API Reference

Dashboard에서 직접 API를 테스트할 수 있습니다:
- 우측에 예시 코드 제공
- 다양한 언어 지원 (Node.js, Python, Ruby 등)
- 실시간으로 결과 확인

## 체크리스트

v2를 완료하기 전에 다음을 확인하세요:

- [ ] Stripe 계정 생성 완료
- [ ] Test Mode 활성화 확인
- [ ] Secret Key 복사 및 안전하게 저장
- [ ] 테스트 카드 번호 숙지 (`4242 4242 4242 4242`)
- [ ] Dashboard 주요 메뉴 확인
- [ ] `.gitignore`에 `.env` 추가 계획

## 다음 단계

v3에서는 TypeScript 프로젝트를 초기화하고 개발 환경을 설정합니다.

준비할 것:
- Node.js 설치 (v18 이상)
- 텍스트 에디터 (VS Code 권장)
- 터미널/커맨드 라인 기본 지식

---

**작성일**: 2025-11-28
**상태**: ✅ 완료
**다음**: v3 - 개발 환경 설정