9. 결제 연동

이 단계에서 하는 것: 머니노트에 프리미엄 결제 기능을 추가한다. 토스페이먼츠 테스트 모드에서 결제창을 열고, 서버가 결제 결과와 금액을 확인해 승인하도록 구현한다. 다음 단계로 넘길 것: 테스트 모드에서 결제 요청·서버 승인·프리미엄 전환이 동작하는 앱.

이 단계에서는 더 많은 통계와 AI 요약을 제공하는 머니노트 프리미엄 결제를 구현한다. 결제 승인은 서버에서 처리한다(confirm). 사용자가 브라우저에서 보내는 금액이나 성공 여부를 바꿀 수 있기 때문이다. 카드번호는 우리 서버를 거치지 않고 사용자와 토스페이먼츠 사이에서만 전달된다.

토스페이먼츠 공식 문서에 표시되는 테스트 키를 사용하므로 실습을 위해 별도 계정이나 키를 발급받을 필요는 없다. 결제창과 서버 승인 코드는 Claude에게 구현을 맡기고, 사람은 결제 흐름과 금액 확인 코드를 검토한다.

[사람] 실제 결제를 시작할 때: 토스페이먼츠에 가입해 본인 키를 발급받는다 → https://www.tosspayments.com (개발자센터). 이 실습에서는 공개 테스트 키를 사용한다.

준비 확인

앞 단계까지 마쳐 로그인·거래·통계·AI가 동작한다.

따라하기

단계 1 — [확인] 테스트 키는 공개 값이다

토스페이먼츠 공식 문서의 API 키 페이지(https://docs.tosspayments.com/reference/using-api/api-keys)에는 누구나 쓸 수 있는 테스트용 클라이언트 키(test_ck_…)와 시크릿 키(test_sk_…)가 공개돼 있다. 공개된 값이라 AI가 문서를 찾아 .env.local에 넣어도 된다 — 다음 단계 프롬프트가 그렇게 시킨다. 실서비스 키(live)는 다르다. 사람이 발급받아 .env.local에 직접 넣고, 대화창에는 치지 않는다.

키에는 두 종류가 있다. test_ck_는 결제창 방식, test_gck_는 결제위젯 방식이다. 아키텍처 문서가 정한 결제 방식의 짝을 AI가 골랐는지 .env.local을 열어 확인한다.

단계 2 — [Claude] 백엔드: 결제 승인과 프리미엄 전환

앞에서 설정한 백엔드 개발자와 프론트엔드 개발자 서브에이전트를 다시 사용한다. 앞 단계에서 미뤄 둔 결제 기능을 이제 구현한다. 백엔드는 승인과 프리미엄 전환을, 프론트엔드는 결제창을 담당한다.

프론트엔드가 요청할 결제 승인 API를 먼저 구현한다.

백엔드 개발자 서브에이전트로, 앞에서 미뤄 둔 결제의 서버 쪽을 docs/API명세.md 1.0대로 만들어줘.토스페이먼츠 최신 v2 SDK를 쓴다. 승인(confirm) API와 SDK 사용법은 공식 문서(docs.tosspayments.com)를 찾아 확인하고 기억으로 쓰지 마.테스트 키도 공식 문서에 있는 것을 찾아 .env.local에 넣어.명세에 없는 세부는 공통 규칙대로 네가 정하고 보고에 적어. 명세·ERD는 고치지 않는다.

이렇게 나오면 성공: 결제 승인을 서버에서 확인하는 API가 생기고, 승인되면 그 사용자가 프리미엄이 된다. .env.local에 테스트 키 두 개가 들어갔고, 시크릿 키는 클라이언트 번들에 노출되지 않는다. 승인 코드가 응답 금액을 서버가 가진 가격과 대조하는지는 뒤의 [사람 검증]에서 본다.

단계 3 — [Claude] 프론트엔드: 결제 버튼과 결제창 연결하기

앞 단계에서 통계 화면에 만든 결제 버튼을 토스페이먼츠 결제창에 연결한다.

프론트엔드 개발자 서브에이전트로, 앞에서 미뤄 둔 결제 화면을 붙여줘. 결제창 SDK 사용법은 토스페이먼츠 공식 문서를 찾아 확인하고 기억으로 쓰지 마.통계 화면의 결제 버튼을 누르면 클라이언트 키로 토스 결제창을 띄우고, 끝나면 서버 승인 결과를 받아 보여줘. 프리미엄이 되면 같은 자리에 AI 요약이 뜨게 해. 실패·취소도 처리해.

클라이언트 키는 NEXT_PUBLIC_을 붙여 화면에서 결제창을 여는 공개 값이고, 시크릿 키는 결제 승인용 서버 전용이라 NEXT_PUBLIC_을 붙이지 않는다. .env.local을 열어 AI가 그렇게 나눴는지 본다. 이 두 이름은 배포 단계 환경변수에서 그대로 다시 쓴다.

이렇게 나오면 성공: 버튼 → 결제창 → 서버 승인(confirm) → 완료 흐름이 이어지고, 프리미엄이 되면 AI 요약이 그 자리에 뜬다. 두 단계 모두 AI가 "정하지 못한 것"(승인 API 제한 시간, 주문 이름, 실패 뒤 돌아갈 화면 등)을 열 건 안팎 남기는 것이 정상이다 — "명세 1.0대로, 나머지는 네가 정해"라고 한 번만 답한다.

[확인] .env.example도 갱신한다. 환경변수 두 개를 추가했으므로 견본 파일에 변수 이름을 기록한다. 실제 키 값은 넣지 않는다.

.env.local에 있는 변수 이름 중 .env.example에 빠진 것을 더해줘. 값은 비우고 이름만. 이미 있으면 그대로 둬.

단계 4 — [사람 검증] 테스트 결제를 직접 진행하기

사람이 결제 전후 화면과 서버 승인 결과를 직접 확인한다. 서버가 꺼져 있으면 먼저 띄우게 한다.

서버 실행해서 url 알려줘. 내가 확인해볼게

AI가 알려 준 주소에서 통계 화면을 먼저 연다. AI 요약 자리에 결제를 권하는 버튼이 보여야 한다 — 아직 프리미엄이 아니니까. 요약 문장은 안 보인다.
그 버튼을 눌러 결제로 넘어간다.
토스 결제창에서 테스트 결제 수단으로 결제한다. 테스트 모드라 실제로 청구되지 않는다.
결제가 끝나면 다시 통계 화면으로 간다. 같은 자리에 버튼이 사라지고 AI 요약 문장이 바로 떠야 한다.
AI에게 "결제 승인 코드에서 응답 금액과 서버가 가진 가격을 대조해 다르면 실패로 처리하는 부분을 열어서 보여줘"라고 요청한다. 파일을 직접 열어 금액 비교와 실패 처리가 구현되었는지 확인한다.

이렇게 나오면 성공: 결제 전에는 버튼, 결제 후에는 요약 문장이 같은 자리에 뜬다. 테스트 결제가 서버 confirm을 거쳐 승인됐고, 금액 대조 코드를 눈으로 확인했다.

이 단계 마무리

결제창 → 서버 승인(confirm) → 완료 흐름이 동작한다. 카드번호는 우리 서버를 거치지 않고, 결제 승인만 서버가 확인한다.
앞에서 설정한 백엔드·프론트엔드 서브에이전트를 다시 사용했다. 백엔드는 결제 승인을, 프론트엔드는 결제창을 담당했다.
토스페이먼츠 공개 테스트 키를 사용해 결제 흐름을 확인했다.
실서비스로 가려면: 토스페이먼츠에 가입해 본인 키(live)로 바꾸고, 배포 단계에서 그 키를 Vercel 환경변수에 넣는다.
막히면: 결제 승인이 안 되면 시크릿 키가 서버 전용 환경변수(클라이언트 노출 없음)로 들어갔는지, 결제창 방식의 키(test_ck_·test_sk_)인지 확인한다.
결제 테스트를 마치지 못했다면: 실습을 계속하기 위해 테스트 계정의 프리미엄 상태를 임시로 설정한다. 결제 흐름은 문제를 해결한 뒤 다시 확인한다.

DBA 서브에이전트로, demo@moneynote.dev 계정을 프리미엄 상태로 바꿔줘. 결제 흐름은 나중에 다시 확인할 거야.

실제 서비스에는 적용하지 않는다. 결제 없이 프리미엄 권한을 부여하는 실습용 임시 설정이다. 이 계정은 이미 프리미엄이라 결제 버튼이 안 보이니, 결제 흐름을 다시 확인할 때는 새 계정으로 한다.

브라우저 없이도 서버 승인은 확인할 수 있다. 로그인한 채 명세의 결제 승인 엔드포인트에 가짜 결제 키·주문번호와 금액 4900을 보내면 결제사가 거절해 400과 사유가 돌아오고, 금액을 1000으로 보내면 결제사를 부르기 전에 400이 돌아온다. 둘 다 서버가 판정한다는 증거다.