5-3. 결제 시스템 붙이기
앞 클립들에서 데이터를 저장하고(5-1), 누가 쓰는지 확인하는 로그인까지 그렸다면 — 이제 가장 떨리는 단계, "돈을 받는 것"입니다. 보통 결제는 로그인한 사용자에게 "이 기능을 쓰려면 결제하세요"라고 붙입니다. 미리 약속할게요. 이 클립은 '딸깍 한 번에 월 천만원' 같은 허황된 약속을 하지 않습니다. 대신 두 가지를 정직하게 알려 드려요. (1) 테스트 모드로 결제 흐름을 "지금 당장" 만드는 법, 그리고 (2) 실제로 진짜 돈을 받으려면 어떤 현실 요건(사업자등록·심사·세금)이 기다리는지. 코드는 여전히 에이전트가 짭니다. 여러분은 "안전하게 무엇을 시킬지"만 알면 됩니다.
1. 결제는 왜 특별히 더 조심스러운가
지금까지 만든 기능이 잘못되면 "화면이 안 뜨네" 정도였습니다. 그런데 결제는 셋이 한꺼번에 얽힙니다 — 남의 돈, 남의 개인정보(카드번호), 그리고 법규. 버그 하나가 곧 금전 사고이고, 카드정보를 잘못 다루면 보안 사고이며, 절차를 건너뛰면 법적 문제가 됩니다.
세 가지가 동시에 얽힘
- 돈: 금액·환불·중복결제 — 실수가 곧 손해이자 분쟁입니다.
- 개인정보: 카드번호는 세상에서 가장 민감한 데이터 중 하나입니다.
- 법규: 사업자·세금·약관 등 "지켜야 할 규칙"이 따라붙습니다.
"직접 안 만진다"
- 위험한 부분(카드정보·돈 흐름)은 전문 업체에 통째로 위임합니다.
- 우리 앱은 "결제해 주세요"라고 부르고 '성공/실패' 결과만 받습니다.
- 먼저 테스트 모드로 흐름을 완성하고, 실제 수금은 그 다음입니다.
핵심은 "위험한 일은 우리가 직접 하지 않는다"입니다. 다행히 결제 세계에는 이 위험을 대신 짊어져 주는 전문 업체들이 있습니다. 그게 다음에 나올 "황금 원칙"의 주인공이에요.
2. ★ 황금 원칙 — 우리는 카드번호를 절대 직접 만지지 않는다
이 클립에서 딱 하나만 가져간다면 바로 이것입니다. 여러분의 웹앱은 카드번호를 받지도, 저장하지도, 보지도 않습니다. 카드정보는 결제대행사(PG)나 Stripe가 제공하는 "호스팅 결제창"이 대신 받아 처리하고, 우리 앱에는 오직 "성공했어요 / 실패했어요"라는 결과만 돌아옵니다.
카드정보를 내 앱이 직접 처리
- 화면에 카드번호 입력칸을 직접 만들어 내 서버로 받기
- 카드번호·CVC를 DB나 코드 어딘가에 저장
- 비밀 키(시크릿)를 화면(프론트엔드) 코드에 박아 넣기
PG·Stripe에 위임
- 업체가 주는 호스팅 결제창을 띄워 카드정보를 그쪽이 받게
- 내 앱은 '성공/실패' 결과만 수신
- 비밀 키는 화면이 아닌 서버(서버리스 함수)에만 — 환경변수로
★ '공개 키'와 '비밀 키(시크릿)'는 전혀 다릅니다. 결제사는 보통 키를 두 종류로 줍니다. 공개 키(publishable/공개용)는 화면에 있어도 괜찮지만, 비밀 키(secret key)는 절대 화면 코드에 넣으면 안 됩니다. 화면 코드는 누구나 브라우저에서 들여다볼 수 있어서, 시크릿이 노출되면 남이 내 계정으로 결제를 만들 수 있어요. 비밀 키는 사용자 눈에 닿지 않는 서버(서버리스 함수)에만, 그것도 환경변수(키를 코드 대신 비밀 보관함에 넣고 이름표로만 부르는 방식)로 둡니다. 에이전트에게 시킬 때 이 한마디를 꼭 못 박으세요.
3. 두 갈래 — 국내(토스페이먼츠) vs 글로벌(Stripe·MoR)
"그 전문 업체, 뭘 쓰면 되나요?" 크게 두 갈래입니다. 누구에게 팔 거냐(국내냐 해외냐)로 갈립니다. 정답은 없고, 여러분 상황에 맞춰 고르면 됩니다.
토스페이먼츠
- 국내 신용카드·간편결제(카카오페이·네이버페이 등)에 강합니다.
- 한국어 문서·테스트 환경이 잘 되어 있어 입문에 친절합니다.
- 단, 실제 운영(진짜 수금)엔 사업자등록·가맹 심사가 필요합니다. 테스트 모드 연동은 가입만으로 먼저 해볼 수 있어요.
Stripe (또는 MoR)
- 글로벌 결제의 사실상 표준. 다양한 나라·통화를 받습니다.
- 다만 한국은 Stripe 지원 국가가 아니라서, 한국 개인이나 한국 법인 명의로는 Stripe 계정을 직접 열 수 없습니다. 지원 국가(예: 미국)에 사업체가 있어야 하고, Stripe Atlas로 미국 법인을 세우는 길이 대표적입니다. (지원 국가 목록은 stripe.com/global에서 확인하세요.)
- 대안 → 아래 MoR를 쓰면 해외 법인 없이도 글로벌 결제를 대행할 수 있습니다.
MoR(Merchant of Record, 판매·세금 대행 사업자)가 뭘까요? 한 문장으로, "내 대신 '판매자'가 되어 결제·세금·환불을 통째로 대행해 주는 서비스"입니다. Paddle · Lemon Squeezy · Polar 같은 곳이 대표적이고, 이들을 끼면 해외 법인 설립 없이도 전 세계에 디지털 상품을 팔 수 있는 길이 열립니다(특히 1인 개발자·소규모 SaaS에서 인기).
💡 여기 숫자나 "된다/안 된다"를 외우지 마세요. 가입 가능 여부, 수수료, 정산 주기, 지원 국가, 필요한 서류 — 이런 정책은 나라·시점·서비스마다 다르고 자주 바뀝니다. 그러니 "토스는 며칠, Stripe 수수료는 몇 %"처럼 제가 숫자를 박아 드리지 않습니다(그게 정직한 태도예요). 실제로 결정하기 전, 각 서비스의 가격·약관 페이지에서 그 시점의 기준을 직접 확인하세요. 헷갈리면 에이전트에게 "내 상황(국내/해외, 개인/사업자)에 토스페이먼츠와 MoR 중 뭐가 맞는지, 각자 어떤 요건이 필요한지 최신 기준으로 정리해줘"라고 물어도 좋습니다.
4. 단건 결제 vs 구독(반복 결제) — 한 단락 정리
결제에는 크게 두 모양이 있습니다. 단건 결제(One-time)는 "한 번 사고 끝" — 전자책 한 권, 템플릿 하나처럼 한 번 돈을 받는 방식입니다. 구독(Subscription)은 "매달(또는 매년) 자동으로" 돈이 빠져나가는 방식이라, 넷플릭스처럼 반복 결제·자동 갱신·해지까지 챙겨야 해서 한 단계 더 복잡합니다. 처음이라면 단건 결제부터 흐름을 완성하고, 익숙해지면 구독으로 넓히는 걸 권합니다. 다행히 어느 쪽이든 결제사가 "구독 상품"이라는 메뉴를 따로 제공하니, 우리는 "단건으로 만들지 구독으로 만들지"만 정해 에이전트에게 말해 주면 됩니다.
5. ★ 무조건 '테스트 모드'부터 — 진짜 카드는 나중에
가장 중요한 안전수칙입니다. 진짜 카드, 진짜 돈으로 시작하지 마세요. 모든 결제사는 '테스트 모드(Test mode)'를 제공합니다. 진짜 돈이 1원도 오가지 않는 연습용 환경에서, 결제사가 문서로 안내하는 "테스트 카드번호"로 결제 흐름 전체를 먼저 완성하는 거예요. (테스트 카드번호는 결제사마다 다르니, 제가 임의의 숫자를 적지 않습니다 — 각 결제사 개발자 문서의 "테스트 카드" 페이지에서 그때의 번호를 복사해 쓰세요.)
결제사 가입 & 테스트 키 발급: 토스페이먼츠(국내) 또는 Stripe·MoR(글로벌)에 가입하고, 테스트용 공개 키 / 비밀 키를 받습니다. 토스페이먼츠는 이메일만으로 가입하면 개발자센터의 API 키 메뉴에서 "개발 연동 체험 상점"의 테스트 키를 바로 볼 수 있어요(사업자등록 없이 가능). 결제위젯용 키는 test_gck(클라이언트 키)·test_gsk(시크릿 키)로, 결제창을 직접 붙이는 API 개별 연동 키는 test_ck·test_sk로 시작합니다. Stripe는 대시보드의 샌드박스(Sandbox)에서 테스트 키를 받습니다. 어느 쪽이든 키 이름에 test가 들어 있으면 테스트용이에요.
에이전트에게 결제 버튼 + 호스팅 결제창 연동: 화면에 "결제하기" 버튼을 만들고, 누르면 결제사가 주는 호스팅 결제창이 뜨도록 연결합니다(카드정보는 그 창이 받습니다 — 우리 앱은 안 받습니다).
서버리스 함수로 비밀 키 숨기기: 결제를 실제로 "승인"하는 단계는 비밀 키가 필요한데, 이건 화면이 아니라 서버리스 함수 안에서 처리하게 합니다(환경변수로). 시크릿이 사용자 눈에 닿지 않게 하는 핵심 단계예요.
성공 결과 처리(웹훅/콜백): 결제가 끝나면 결제사가 "성공했어요"라는 신호(웹훅 또는 결제창이 돌아오는 콜백)를 보냅니다. 그 신호를 받아 "감사합니다" 화면을 띄우거나, 구독을 활성화하는 등 우리 앱의 뒷처리를 합니다.
이 네 박자가 결제의 전부입니다. ②~④의 코드는 모두 에이전트에게 맡기고, 여러분은 "테스트 모드인지, 시크릿이 서버에만 있는지"만 확인하면 됩니다.
6. 복붙 프롬프트 — 테스트 모드로 안전하게
아래 프롬프트들은 프로젝트 폴더에서 실행 중인 코딩 에이전트(터미널의 Claude Code 등)에 붙여넣습니다. 키·주소가 들어갈 자리는 여기에_… 같은 빈칸(플레이스홀더)으로 적어 두었으니, 여러분이 받은 진짜 값으로 바꿔 넣으세요. 셋 다 테스트 모드 전제입니다.
"이 앱에 토스페이먼츠 '테스트 모드' 단건 결제를 붙여줘. 진행 순서: ① 먼저 토스페이먼츠 결제창(SDK)을 붙이는 방법과, 개발자센터의 API 키 메뉴에서 '테스트' 클라이언트 키(test_로 시작)를 어디서 복사하는지 단계별로 알려줘. 결제위젯 키(test_gck)와 API 개별 연동 키(test_ck) 중 어떤 걸 써야 하는지도 내 방식에 맞게 알려줘. ② 화면에 '결제하기' 버튼을 추가하고, 누르면 토스페이먼츠가 제공하는 호스팅 결제창이 뜨도록 연결해줘 — 카드정보는 우리 화면이 직접 받지 말고 그 결제창이 받게 해줘. ③ 금액·주문명 같은 값은 내가 쉽게 바꿀 수 있게 변수로 빼줘. 클라이언트 키 자리는 여기에_테스트_클라이언트_키 로 두고, 비밀 키는 화면 코드에 절대 넣지 마. 지금은 테스트 모드만 만들고, 결제사 공식 문서의 '테스트 카드'로 흐름을 확인할 수 있게 해줘. 한 번에 다 하지 말고 ①→②→③ 순서로, 단계마다 멈춰서 내가 확인하게 해줘."
성공하면 이렇게 보입니다: "결제하기"를 누르면 토스페이먼츠의 결제창이 화면에 뜨고, 결제사 문서의 테스트 카드번호를 넣으면 진짜 돈은 1원도 안 빠지면서 "결제 완료" 흐름이 끝까지 돌아갑니다. 토스페이먼츠 대시보드의 '테스트' 결제 내역에도 방금 결제가 한 줄 찍히죠. 진짜 카드 없이 결제의 전 과정을 눈으로 확인하는 순간입니다.
"이 앱에 Stripe '테스트 모드' 결제를 붙이되, 비밀 키가 화면에 절대 노출되지 않도록 서버리스 함수로 처리해줘. 진행 순서: ① Stripe 샌드박스(테스트 환경)에서 '공개 키(pk_test_)'와 '비밀 키(sk_test_)'를 어디서 받는지 알려줘. ② '결제하기' 버튼을 누르면, 우리 화면이 아니라 서버리스 함수(예: Vercel의 /api 함수)가 Stripe 비밀 키로 'Checkout 세션(호스팅 결제창)'을 만들고, 사용자를 그 Stripe 결제 페이지로 보내도록 짜줘. 비밀 키는 코드에 박지 말고 환경변수(예: 이름은 STRIPE_SECRET_KEY)로 읽게 하고, 그 환경변수를 어디에 등록하는지도 알려줘. ③ 결제가 끝나면 우리 앱의 '결제 완료' 페이지로 돌아오게 해줘. 지금은 테스트 모드만 만들고, 공식 문서의 테스트 카드로 확인할 수 있게 해줘. (참고: 내가 한국에서 Stripe를 직접 못 쓰는 상황이면, 같은 흐름을 Paddle·Lemon Squeezy·Polar 같은 MoR 서비스로 대체하는 방법도 함께 제안해줘.)"
성공하면 이렇게 보입니다: "결제하기"를 누르면 Stripe가 호스팅하는 결제 페이지로 이동하고, 테스트 카드로 결제하면 다시 우리 앱의 "결제 완료" 화면으로 돌아옵니다. 무엇보다 브라우저에서 화면 코드를 열어 봐도 비밀 키가 보이지 않습니다 — 시크릿이 서버리스 함수 안(환경변수)에만 있기 때문이죠. "위험한 일은 서버가, 화면은 결과만"이라는 황금 원칙이 실제로 동작하는 걸 확인하는 순간입니다.
"결제가 성공했을 때 우리 앱이 뒷처리를 하도록 만들어줘. ① 결제사가 보내는 '결제 성공' 웹훅(또는 결제창이 돌아오는 콜백)을 받는 서버리스 함수를 만들어줘. ② 그 신호가 진짜 결제사에서 온 게 맞는지 검증하는 단계(서명/시크릿 확인)도 빼먹지 말고 넣어줘 — 가짜 신호로 결제를 인정하면 안 되니까. ③ 검증을 통과하면, 5-1에서 만든 Supabase의 사용자 데이터에 '이 사용자는 결제(또는 구독)가 활성화됨'을 기록하고, 화면에는 '결제가 완료됐어요 ✅'를 보여줘. 실패하면 에러를 안전하게 처리하고 사용자에게 안내해줘. 지금은 테스트 모드 기준으로 만들어줘."
성공하면 이렇게 보입니다: 테스트 결제를 마치면 우리 앱이 결제사의 "성공" 신호를 받아, 그 사용자에게 "결제 완료" 표시를 띄우고 — 구독이라면 잠겨 있던 기능이 풀립니다. "돈을 받았다 → 권한을 준다"는 서비스의 핵심 한 바퀴가 돌아가는 모습을, 진짜 돈 없이 테스트로 미리 확인하는 거예요.
💡 왜 ②(검증)이 중요할까요? 웹훅 주소는 인터넷에 열려 있어서, 누군가 가짜로 "결제 성공!" 신호를 흉내 낼 수도 있습니다. 그래서 결제사는 "이 신호가 진짜 우리에게서 왔다"는 서명(시그니처)을 함께 보냅니다. 그걸 비밀 키로 확인해야 가짜를 걸러낼 수 있어요. 이 검증을 빼면 "결제 안 하고도 기능 풀기"가 가능해지니, 프롬프트에서 꼭 못 박으세요.
7. ★ 정직한 현실 안내 — '테스트'와 '진짜 수금'은 다릅니다
여기서 가장 솔직해야 할 대목입니다. 방금 만든 건 '프로토타입(테스트 모드)'입니다. 누구나 지금 당장 만들 수 있어요. 하지만 '진짜 돈'을 받는 단계로 넘어가려면, 코드가 아니라 '현실 세계의 요건'이 기다립니다. 이걸 숨기는 강의가 많지만, 저는 그러지 않을게요.
★ 실제 수금에 보통 따라오는 현실 요건들 (서비스·국가·시점마다 다르니 반드시 직접 확인):
① 사업자등록: 진짜 돈을 받으려면 대개 개인사업자 등록 등 "사업자" 자격이 필요합니다.
② 가맹/심사: 토스페이먼츠 같은 국내 PG는 실서비스 전 가맹 심사·서류 제출을 거칩니다(승인 전엔 테스트만 가능).
③ 약관·환불·개인정보 처리방침: 이용약관·환불정책 고지, 개인정보 동의 등 법이 요구하는 문서가 필요합니다.
④ 세금: 매출이 생기면 부가세·종합소득세 등 세무 처리가 따라옵니다(특히 해외 판매는 더 복잡 — MoR가 이 부분을 대행하는 이유이기도 합니다).
즉 "프로토타입을 만드는 능력"과 "사업을 합법적으로 운영하는 일"은 다른 문제입니다. 이 클립은 전자를 확실히 쥐여 드리고, 후자는 "이런 게 기다린다"고 정직하게 알려 드리는 데까지입니다. 막연하면 세무·법무는 전문가(세무사 등)와 상의하세요.
8. 막히면 이렇게 — 트러블슈팅
결제 연동은 단계가 많아 한두 번 막히는 게 정상입니다. 아래 순서로 점검하고, 늘 그렇듯 빨간 에러 메시지를 그대로 복사해 에이전트에게 주는 것이 가장 강력합니다.
💡 ① 결제창이 안 떠요 → 십중팔구 키 문제입니다. '테스트 모드'의 공개 키를 정확히(오타·앞뒤 공백 없이) 넣었는지, 실수로 운영(Live) 키를 쓰진 않았는지 확인하세요.
💡 ② "키가 노출됐다"는 경고 메일을 받았어요 → 비밀 키를 화면 코드에 넣었을 가능성이 큽니다. 즉시 대시보드에서 그 키를 폐기/재발급(rotate)하고, 비밀 키는 서버리스 함수의 환경변수로만 옮기세요. (테스트 키라도 습관을 들이는 게 중요합니다.)
💡 ③ 결제는 됐는데 "결제 완료"로 안 넘어가요 → 대개 웹훅/콜백 처리 문제입니다. 웹훅 주소를 결제사 대시보드에 등록했는지, 서명 검증이 통과되는지 확인하세요. 에이전트에게 "웹훅이 안 들어오는데 등록 주소와 서명 검증을 점검해줘"라고 맡기면 됩니다.
💡 ④ 그래도 모르겠으면 → 브라우저 콘솔(맥
Cmd+Option+I/ 윈도우F12)이나 서버리스 함수의 로그에 뜬 빨간 에러를 통째로 복사해 "이 에러가 뜨는데 고쳐줘"라고 주세요.
우리는 카드번호를 절대 직접 만지지 않습니다. 카드정보는 결제사의 호스팅 결제창이 받고, 내 앱은 '성공/실패'만 받습니다. 비밀 키는 화면이 아니라 서버(서버리스 함수)에 환경변수로, 그리고 무조건 테스트 모드부터. 국내는 토스페이먼츠, 해외는 Stripe(한국 명의로는 직접 가입이 안 되니 해외 법인 또는 MoR). 마지막으로 가장 정직한 한 줄 — 프로토타입은 지금 만들 수 있지만, '진짜 돈'을 받으려면 사업자등록·심사·약관·세금이라는 현실 요건이 따라옵니다. 수수료·정책·요건은 시점마다 다르니 각 서비스 약관에서 직접 확인하세요.