← 목록으로
2026-02-25plans

Toss Payments 프로덕션 실결제 연동 Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Toss 프로덕션 키 적용 + R2 다운로드 URL 연결 + 실결제 E2E 검증으로 richbukae.com 실서비스 가동

Architecture: Plan 1(결제→배송 플로우 완성) 완료 후 진행. 코드 변경 최소화 — 대부분 Vercel env 설정으로 해결. 단, 실결제 테스트는 최소 금액(1,000원)으로 1건 수행 후 즉시 환불. Toss 프로덕션 키는 CEO가 제공하므로 CEO 언블로킹 후 착수.

Tech Stack: Vercel CLI, Toss Payments API v1, Cloudflare R2, curl

관련 태스크: b17f96d2

선행 조건: Plan 1 (2026-02-25-richbukae-payment-delivery-flow.md) 완료 필수

전제 조건 체크리스트

CEO로부터 아래 항목 수령 후 착수:

  • TOSS_SECRET_KEY (프로덕션 시크릿 키, live_sk_ 접두사)
  • NEXT_PUBLIC_TOSS_CLIENT_KEY (프로덕션 클라이언트 키, live_ck_ 접두사)
  • PRODUCT_PDF_URL (Cloudflare R2 PDF bundle zip URL)
  • PRODUCT_SKILLS_URL (Cloudflare R2 Skills bundle zip URL)
  • PRODUCT_NOTION_URL (Notion 템플릿 공유 URL)

Task 1: Vercel 프로덕션 Env 설정

Files:

  • Read: projects/richbukae-store/.env.local (현재 로컬 설정 확인)

Step 1: 현재 Vercel env 목록 확인

cd projects/richbukae-store && vercel env ls production

Expected: 현재 설정된 env 목록 출력

Step 2: Toss 프로덕션 키 설정

cd projects/richbukae-store

# 시크릿 키 (서버사이드)
vercel env add TOSS_SECRET_KEY production
# 입력값: live_sk_XXX... (CEO 제공)

# 클라이언트 키 (퍼블릭)
vercel env add NEXT_PUBLIC_TOSS_CLIENT_KEY production
# 입력값: live_ck_XXX... (CEO 제공)

Expected: 각각 "✅ Added Environment Variable" 메시지

Step 3: R2 다운로드 URL 설정

cd projects/richbukae-store

vercel env add PRODUCT_PDF_URL production
# 입력값: https://pub-843...r2.dev/ai-architect/pdf-bundle.zip (CEO 제공)

vercel env add PRODUCT_SKILLS_URL production
# 입력값: https://pub-843...r2.dev/ai-architect/skills-bundle.zip (CEO 제공)

vercel env add PRODUCT_NOTION_URL production
# 입력값: https://www.notion.so/... (CEO 제공)

Step 4: 설정 확인

cd projects/richbukae-store && vercel env ls production | grep -E "TOSS|PRODUCT"

Expected: 5개 항목 모두 출력

Task 2: 프로덕션 배포 (CEO 최종 승인 후)

⚠️ 이 태스크는 CEO(머스크 VP) 승인 후 실행. 자비스 단독 결정 금지.

Step 1: 빌드 검증

cd projects/richbukae-store && npm run build 2>&1 | tail -15

Expected: ✓ Compiled successfully

Step 2: Vercel 프로덕션 배포

cd projects/richbukae-store && vercel --prod 2>&1 | tail -5

Expected: ✅ Production: https://richbukae.com [Xm]

Step 3: 배포 직후 스모크 테스트

# 메인 페이지
curl -s -o /dev/null -w "%{http_code}" "https://richbukae.com"
# Expected: 200

# 체크아웃 페이지
curl -s -o /dev/null -w "%{http_code}" "https://richbukae.com/checkout"
# Expected: 200

# TossPayments 스크립트 로드 확인
curl -s "https://richbukae.com/checkout" | grep -c "tosspayments"
# Expected: 1 이상

Task 3: 실결제 E2E 테스트 (최소 금액)

⚠️ 실결제이므로 반드시 CEO 입회 하에 진행. 환불 즉시 처리.

Step 1: Toss 프로덕션 대시보드 준비

Step 2: 브라우저에서 실결제 테스트

1. https://richbukae.com/checkout 접속
2. 이메일 입력: test@newbizsoft.com (CEO 이메일)
3. 번들 선택 (최소 금액 상품이면 개별 책 선택)
4. "결제하기" 클릭
5. Toss 결제창 팝업 확인
6. 테스트 카드: 실제 카드 또는 Toss 제공 테스트 카드 사용
7. 결제 완료 → /success 페이지 도달 확인

Step 3: 결제 완료 후 검증 항목

# 1. success 페이지 다운로드 링크 표시 확인 (브라우저에서 직접 확인)

# 2. SALES_OS DB 주문 기록 확인
turso db shell sales-os "SELECT order_id, email, amount, status FROM orders ORDER BY created_at DESC LIMIT 1;"
# Expected: 방금 결제한 주문 1건

# 3. PDF 다운로드 링크 작동 확인
# success 페이지의 PDF 다운로드 버튼 클릭 → R2 URL로 리다이렉트 확인

# 4. 배송 이메일 수신 확인 (test@newbizsoft.com)

Step 4: 즉시 환불 처리

ORDER_ID="실제_주문ID"
PAYMENT_KEY="실제_paymentKey"

curl -s -X POST "https://api.tosspayments.com/v1/payments/${PAYMENT_KEY}/cancel" \
  -H "Authorization: Basic $(echo -n 'live_sk_XXX:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"cancelReason":"테스트 결제 환불"}' \
  | python3 -m json.tool

Expected: "status": "CANCELED" 포함 응답

Step 5: 커밋

git add -A
git commit -m "feat(richbukae): production Toss integration live — E2E verified"

Task 4: 모니터링 및 에러 알림 설정

Files:

  • Modify: projects/richbukae-store/src/app/api/payment/confirm/route.ts

Step 1: 결제 실패 시 CEO 알림 추가

현재 코드에 결제 실패 시 Telegram 알림 추가 (선택):

// confirm/route.ts 상단에 추가
async function notifyPaymentFailure(orderId: string, error: string) {
  const token = process.env.TELEGRAM_BOT_TOKEN;
  const chatId = process.env.TELEGRAM_CHAT_ID;
  if (!token || !chatId) return;
  await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chat_id: chatId,
      text: `🚨 richbukae 결제 실패\nOrderId: ${orderId}\nError: ${error}`,
    }),
  }).catch(() => {});
}

⚠️ Telegram 토큰/채팅ID는 CEO 채널 것이므로 자비스 승인 없이 추가 금지. 선택 사항.

Step 2: Vercel 함수 로그 확인 방법

# 배포 후 실시간 로그 확인
vercel logs https://richbukae.com --follow

Step 3: 최종 커밋

git add -A
git commit -m "feat(richbukae): add payment failure monitoring"

완료 체크리스트

  • Toss 프로덕션 키 2개 Vercel env 설정됨
  • R2 다운로드 URL 3개 Vercel env 설정됨
  • 프로덕션 배포 완료 (CEO 승인 후)
  • 실결제 테스트 1건 성공
  • SALES_OS DB에 주문 기록 확인됨
  • 배송 이메일 수신 확인됨
  • 테스트 결제 환불 완료
  • 모니터링 설정 완료

롤백 플랜

실결제 중 이슈 발생 시:

# 즉시 구버전으로 롤백
vercel rollback https://richbukae.com

# Toss 프로덕션 키 임시 제거
cd projects/richbukae-store
vercel env rm TOSS_SECRET_KEY production
vercel env rm NEXT_PUBLIC_TOSS_CLIENT_KEY production
vercel --prod
plans/2026/02/25/toss-production-integration.md