결제 + API — 외부 서비스와 대화하는 흐름

왜 이 레슨이 필요한가

본인 SaaS는 혼자 돌지 않아요. 결제는 토스페이먼츠가, AI는 Claude API가, 알림은 카카오톡 채널이 — 전부 다른 회사의 서비스가 도와요. 이 "외부 서비스와 대화"는 한 패턴으로 정리할 수 있어요. 한 번 익히면 어떤 외부 서비스든 "아 그거랑 똑같지" 됩니다.

/v1-money-flow 스킬은 결제 흐름을 메인 사례로 깔고, 같은 패턴이 API 호출 / webhook에도 적용된다는 걸 보여줘요.

결제 흐름 — "카드 입력 → PG → 우리 DB는 결과만"

가장 자주 묻는 오해 — "결제하려면 우리도 카드 번호를 받아서 저장해야 하나요?" 아니요. 절대 안 됩니다. 한국 법(전자금융거래법)상 그래도 안 되고, 보안 사고 시 책임이 너무 커요.

그래서 모든 SaaS는 PG(Payment Gateway)라는 결제 전문 회사에 위탁해요. 한국에서는 토스페이먼츠 / 포트원(아임포트) / KG이니시스가 대표적. LEARN은 토스페이먼츠를 권장 (UX 좋고 문서 친절).

1. 사용자가 본인 SaaS에서 "결제" 버튼 클릭
2. 본인 서버가 PG의 결제창 URL을 만들어 사용자에게 전달
3. 사용자가 PG 결제창(토스 페이지)에서 카드 정보 입력 — 이때 카드 정보는 본인 서버에 안 옴!
4. PG가 카드사와 통신 → 승인 결과 받음
5. PG가 본인 서버에 결과 통보 (webhook 또는 redirect) — "결제 ID xyz123, 성공, 1만 원"
6. 본인 서버가 DB에 저장: payments 표에 (user_id, payment_id, amount, status) 한 줄
7. 사용자에게 "결제 완료" 화면 보여줌

우리 DB의 payments 표 — 결과만 보관

보다시피 카드 번호·CVC·유효기간 어디에도 없어요. payment_key는 PG가 부여한 식별자. 나중에 환불·조회 시 이 키로 PG에 다시 물어봄.

API 호출 — 결제와 같은 패턴

결제는 "외부 서비스(PG)에 일을 시키고 결과 받기"예요. 이 패턴이 다른 외부 서비스 호출에도 그대로 적용돼요. 이게 API의 핵심이에요.

전부 같은 패턴이에요: (1) 우리 서버 → 외부 서비스에 요청 (2) 결과 받음 (3) DB에 결과만 저장. 하나만 익히면 새로운 외부 서비스가 나타나도 "아 그것도 똑같지" 됩니다.

API key — 외부 서비스에 보여주는 신분증

외부 서비스에 요청을 보낼 때 "이거 누가 보낸 거야?"라는 질문이 와요. 답이 API key예요. 외부 서비스가 발급해주는 긴 문자열이에요. 예시:

ANTHROPIC_API_KEY=sk-ant-api03-Kix3jL...8bN3vXz
TOSS_SECRET_KEY=test_sk_LkKEypNArWZxZx4WPRP0lmeaxYG5
KAKAO_API_KEY=a1b2c3d4e5f6...

이 키는 비밀번호급 비밀이에요. 누구든 이 키만 손에 넣으면 본인 이름으로 외부 서비스를 호출할 수 있고, 비용도 본인에게 청구돼요. 그래서 절대 (1) 코드에 직접 적지 않고 (2) GitHub에 올리지 않아요. .env 파일에 적고, .env는 .gitignore에 등록해서 git에서 제외해요.

ANTHROPIC_API_KEY=sk-ant-api03-실제키
TOSS_SECRET_KEY=test_sk_실제키
KAKAO_API_KEY=실제키

.env
.env.local
.env.production

webhook — 외부 서비스가 우리에게 거는 전화

API 호출은 우리가 외부에 거는 전화예요. 반대로 외부 서비스가 우리에게 거는 전화가 webhook이에요. 가장 자주 쓰이는 곳이 결제예요. 사용자가 토스 결제창에서 카드 입력하고 승인되는 데 5~30초 걸려요. 그동안 우리 서버는 가만히 있다가 — 토스가 "결제 완료됐어!" 하고 전화 걸어줘요. 그게 webhook.

webhook을 받으려면 우리 서버에 "토스가 부를 수 있는 URL"이 있어야 해요. 예: https://본인서비스.com/webhooks/toss. 토스 대시보드에 이 URL을 등록해두면, 결제 완료 시 토스가 자동으로 호출.

스킬 호출 + 묻는 질문

/v1-money-flow

스킬 결과물 — 본인 외부 서비스 지도

답변이 모이면 스킬이 본인 SaaS의 외부 서비스 의존성 지도를 그려줘요. 어떤 키들을 .env에 두어야 하는지까지 정리.

[본인 SaaS]
  ↔ 토스페이먼츠 (PG)
      .env 키:    TOSS_CLIENT_KEY, TOSS_SECRET_KEY
      webhook:    /webhooks/toss
      DB 표:      payments

  ↔ Claude API (AI 요약)
      .env 키:    ANTHROPIC_API_KEY
      DB 표:      ai_generations

  ↔ 카카오 비즈니스 API (알림)
      .env 키:    KAKAO_API_KEY
      DB 표:      notifications

총 외부 의존성:    3개
필요 .env 키 수:   4개
필요 webhook 수:   1개 (토스)

막히는 지점 — 미리 답

• "PG를 어떤 회사 쓰는 게 좋아요?" → 처음에는 토스페이먼츠 강추. UX 좋고 한국어 문서 친절. 가입·심사 절차도 가장 빠름. Ch.4-12에서 진짜 붙임.
• "실수로 .env를 GitHub에 올려버렸어요." → 즉시 API key를 폐기·재발급하세요. git history에서 지워도 GitHub은 캐시에 남아요. 키 폐기가 가장 빠름.
• "webhook이 우리 서버에 도착했는지 어떻게 확인?" → Rails라면 로그를 보면 됨. 또는 토스 대시보드의 "webhook 전송 이력". Ch.4-12에서 실습.
• "결제 한 번으로 같은 webhook이 여러 번 와요." → 멱등성(idempotency) 처리 필요. 같은 payment_key로 두 번 처리하지 않게 DB에 unique 인덱스. Ch.4-12에서 다룸.
• "무료 SaaS인데 결제 lesson 필요해요?" → 1-5는 개념만 잡는 게 목적. 무료 서비스라면 Ch.4-12를 건너뛰면 됨. 단 다른 외부 API 호출(Claude/카톡)은 같은 패턴이라서 lesson 자체는 유익.