앱에 결제를 추가하는 방법: 체크아웃, 구독, 웹훅

앱에 결제를 추가하는 가장 간단한 방법은 Stripe를 쓰는 것입니다. "구매" 버튼만 필요하고 주문은 직접 처리할 수 있다면 결제 링크를 쓰세요. 앱이 누가 결제했는지 알고 자동으로 반응해야 한다면 Stripe 체크아웃을 쓰세요. 정기 결제라면 구독 모드의 체크아웃과 Stripe의 고객 포털을 함께 쓰세요. 가장 단순한 경우를 제외하면 모든 방식에 웹훅, 즉 결제가 성공했을 때 Stripe가 호출하는 서버 엔드포인트가 필요합니다. 그리고 실제 키로 바꾸기 전에 Stripe의 테스트 키와 테스트 카드로 모든 것을 테스트하세요.

이 가이드는 각 선택지를 설명하고, 대부분의 튜토리얼이 건너뛰는 웹훅 부분과 실제 돈을 받기 전에 확인할 사항을 다룹니다. Stripe 세부 내용은 2026년 9월 기준 Stripe 공식 문서를 따랐습니다.

결제 제공업체를 써야 하는 이유

자체 양식에서 카드 번호를 직접 수집하지 마세요. 카드 데이터를 직접 다루면 PCI DSS(카드 산업 보안 표준)의 적용을 받게 되고, 심각한 책임 문제가 생깁니다. Stripe 같은 결제 제공업체는 결제 양식을 호스팅하고, 카드를 저장하고, 은행 인증을 처리하고, 결과를 앱에 알려 줍니다. 앱은 "고객 X가 Y에 대해 결제했다"는 사실만 알게 됩니다.

이 가이드에서 Stripe를 쓰는 이유는 널리 쓰이고, 문서가 잘 되어 있으며, 대부분의 AI 앱 빌더가 지원하기 때문입니다. 다른 제공업체도 있으며, 그중 일부는 "판매 대행자(merchant of record)" 역할을 맡아 판매세 처리를 대신해 줍니다. 세금 준수가 걱정된다면 이런 모델도 비교해 볼 만합니다.

Stripe로 결제를 받는 세 가지 방식

결제 링크

결제 링크는 Stripe 대시보드에서 코드 없이 만드는, Stripe가 호스팅하는 결제 페이지입니다. 앱의 버튼 뒤에 둘 URL, 이메일로 공유할 URL, QR 코드로 보여 줄 URL을 받을 수 있습니다. Stripe 문서에 따르면 결제 링크로 상품, 구독을 판매하거나 후원을 받을 수 있으며, 고객이 결제 항목을 고르게 하거나 구매 횟수를 제한할 수도 있습니다.

단점은 앱이 특정 로그인 사용자가 결제했다는 사실을 자동으로 알지 못한다는 것입니다. 후원 페이지나 Stripe 이메일 알림을 보고 직접 주문을 처리하는 작은 상점이라면 괜찮습니다. "결제하면 Pro 기능 열기" 같은 경우에는 맞지 않습니다.

Stripe 체크아웃

체크아웃은 서버가 특정 구매를 위해 필요할 때 만드는 결제 페이지입니다. 서버가 Stripe에 무엇을 구매하는지(선택적으로 누가 구매하는지)를 알리면, Stripe가 URL을 돌려주고, 그 URL로 고객을 보냅니다. Stripe 문서는 체크아웃이 일회성 결제와 구독 결제를 모두 지원하며, Stripe가 호스팅하는 전체 페이지, 사이트에 임베드된 페이지, 임베드된 양식 형태를 제공한다고 설명합니다.

흐름은 다음과 같습니다.

1. 고객이 앱에서 구매를 클릭합니다.
2. 여러분의 서버가 비밀 키를 사용해 체크아웃 세션을 만들고, 그 세션에 사용자나 주문을 연결하는 ID를 넣습니다.
3. 고객이 Stripe로 이동해 결제합니다.
4. Stripe가 고객을 결제 완료 페이지로 되돌려 보냅니다.
5. Stripe가 여러분의 웹훅으로 checkout.session.completed 이벤트를 보내고, 서버가 주문을 결제 완료로 표시하거나 접근 권한을 엽니다.

2단계는 반드시 서버에서 해야 합니다. 비밀 키를 사용하기 때문입니다. 이것이 체크아웃에 백엔드가 필요한 가장 큰 이유입니다.

구독

구독은 Stripe에서 설정한 반복 가격으로 구독 모드 체크아웃을 사용합니다. 첫 결제는 위의 흐름과 같습니다. 그 뒤로는 갱신, 카드 실패, 업그레이드, 해지가 시간이 지나면서 일어나는데, 종종 고객이 앱에 없을 때 발생합니다. 그래서 앱은 웹훅을 통해서만 이를 알게 됩니다.

고객이 직접 구독을 관리하게 하려면 Stripe가 제공하는 호스팅 고객 포털을 쓸 수 있습니다. Stripe 문서에 따르면 고객은 포털에서 결제 수단과 청구 정보를 업데이트하고, 구독을 변경하거나 해지하며, 인보이스를 보고 내려받을 수 있습니다. Stripe 대시보드에서 포털을 설정하고, "결제 관리" 버튼을 추가해 고객을 포털로 보내면 됩니다. 이 화면들을 직접 만들 필요가 없습니다.

웹훅: 건너뛸 수 없는 부분

웹훅은 무슨 일이 일어나면 Stripe가 여러분의 서버로 보내는 HTTP 요청입니다. (일반적인 개념은 웹훅이란을 참고하세요.) Stripe의 주문 처리 가이드는 명확합니다. 결제 완료 페이지만으로 주문을 처리하면 안 됩니다. 고객이 결제한 뒤 그 페이지가 열리기 전에 연결이 끊길 수 있기 때문입니다. 구독과 지연 결제 수단에서는 웹훅이 필수입니다.

처리할 가치가 있는 이벤트

올바른 웹훅 처리기의 규칙

이 규칙들은 Stripe의 웹훅 문서에서 가져왔으며, AI가 만든 처리기에서 종종 빠지는 부분입니다.

• 서명을 검증하세요. 각 이벤트에는 Stripe-Signature 헤더가 포함됩니다. 처리기는 엔드포인트의 서명 비밀(whsec_로 시작)로 이를 확인해야 합니다. 이 검증이 없으면 누구나 가짜 "결제 성공" 요청을 서버로 보낼 수 있습니다.
• 원본 요청 본문을 사용하세요. 프레임워크가 본문을 파싱하거나 수정하면 서명 검증이 실패합니다.
• 2xx 응답을 빠르게 반환하고, 오래 걸리는 작업은 그다음에 하세요. 시간 초과는 실패로 집계됩니다.
• 중복을 처리하세요. Stripe는 같은 이벤트를 두 번 이상 보낼 수 있습니다. 처리한 이벤트 ID를 기록하거나, 주문 처리를 두 번 실행해도 안전하게 만드세요.
• 순서를 가정하지 마세요. Stripe는 이벤트가 발생한 순서대로 도착한다고 보장하지 않습니다.
• 재시도를 예상하세요. 실서비스 모드에서 Stripe는 실패한 전송을 최대 3일 동안 재시도하므로, 짧은 장애로 결제를 잃지는 않습니다. 하지만 처리기는 늦게 도착하는 이벤트도 감당할 수 있어야 합니다.

웹훅에는 공개 HTTPS 주소가 필요하므로, 보통 앱을 게시한 뒤에야 동작합니다(개발자는 Stripe CLI로 이벤트를 로컬 컴퓨터에 전달할 수 있습니다).

전체 흐름을 다루는 프롬프트

"Pro 팩"에 대한 일회성 구매를 Stripe 체크아웃으로 추가해 주세요(가격 ID는 STRIPE_PRICE_ID). 체크아웃 세션은 시크릿에 있는 STRIPE_SECRET_KEY를 사용해 서버에서 만들고, 로그인한 사용자의 ID를 세션에 포함해 주세요. POST /api/stripe/webhook 엔드포인트를 추가하고, 원본 요청 본문을 사용해 STRIPE_WEBHOOK_SECRET으로 Stripe 서명을 검증하고, checkout.session.completed를 처리해서 해당 사용자를 Pro 팩 보유자로 표시해 주세요. 같은 이벤트가 두 번 와도 안전하게 해 주세요. 성공 페이지와 취소 페이지도 추가해 주세요. 비밀 키는 브라우저에 절대 노출하지 마세요.

구독이라면 다음을 추가하세요. "구독 모드에서 STRIPE_PRICE_ID를 사용해 주세요. invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted를 처리하고, 결제 관리 버튼을 추가해 Stripe 고객 포털을 열어 주세요."

테스트 모드

Stripe는 샌드박스(테스트) 환경과 실서비스 환경을 분리하고, 각각 다른 키를 제공합니다. 샌드박스 키는 pk_test_, sk_test_, rk_test_로 시작하고, 실서비스 키는 pk_live_, sk_live_, rk_live_로 시작합니다. 테스트 거래는 실제 돈을 움직이지 않습니다.

Stripe 테스트 문서에 나오는 유용한 테스트 카드입니다(미래의 만료일, 임의의 3자리 CVC 사용).

최소한 다음을 테스트하세요.

• 결제가 성공하면 올바른 사용자에게 올바른 기능이 열린다
• 거절된 카드는 명확한 메시지를 보여 주고, 아무것도 열지 않는다
• 결제 직후 브라우저 탭을 닫아도 접근 권한이 생긴다(결제 완료 페이지가 아니라 웹훅이 동작한다는 증명입니다)
• Stripe 페이지에서 취소하면 앱으로 돌아오고, 아무것도 청구되지 않는다
• 구독이라면: 고객 포털에서 해지하고, 접근이 올바른 시점에 끝나는지 확인한다

실서비스 전환

1. Stripe 계정을 활성화하세요. 사업자 정보와 은행 정보를 입력하세요.
2. 앱 시크릿에 실서비스 키를 넣으세요. Stripe는 전체 권한의 비밀 키 대신, 연동에 필요한 권한만 가진 제한된 키를 권장합니다.
3. 실서비스 웹훅 엔드포인트를 만드세요. 게시한 앱을 가리키게 하세요. 실서비스 엔드포인트에는 테스트용과 다른 서명 비밀이 있으므로 값을 업데이트하세요.
4. 상품과 가격을 실서비스 모드에서 다시 만드세요. 테스트 모드의 ID는 실서비스에 존재하지 않습니다.
5. 실제로 소액 구매 한 건을 하고 환불하세요.

모든 키는 코드나 채팅이 아니라 프로젝트 시크릿에 보관하세요. AI로 만든 앱의 보안 체크리스트는 키와 웹훅 검증을 더 자세히 다룹니다.

세금, 환불, 서류

결제에는 코드로 해결되지 않는 의무가 따릅니다. 이것은 세무 조언이 아니니 회계사와 확인하세요.

• 판매세, 부가가치세, GST. 여러분과 고객이 어디에 있느냐에 따라 등록하고, 세금을 부과하고, 신고해야 할 수 있습니다. Stripe Tax는 결제 시 세금을 계산하고 징수하며, 판매가 의무를 발생시킬 수 있는 곳을 모니터링하고, 등록과 신고를 도울 수 있습니다. 다만 책임은 여러분에게 남습니다. 판매 대행자 방식의 제공업체는 더 많은 부분을 대신 처리하는 대안입니다.
• 환불과 분쟁. 출시 전에 환불 정책을 정하고 사이트에 게시하세요. 분쟁(차지백)은 생길 수 있으니, 무엇이 판매되고 전달되었는지 기록을 남기세요.
• 영수증과 인보이스. Stripe가 영수증을 이메일로 보낼 수 있습니다. 사업자는 정식 인보이스가 필요할 수 있습니다.
• 수수료. 모든 제공업체는 거래마다 수수료를 받습니다. 기사에 나온 금액보다는 제공업체의 현재 요금 페이지를 확인하세요.

앱에 맞는 설정

• 후원이나 상품 몇 개: 결제 링크. 비영리 후원 웹사이트 만드는 법을 참고하세요.
• 장바구니가 있는 스토어: 항목 목록과 웹훅이 포함된 체크아웃. 온라인 스토어 만드는 법을 참고하세요.
• SaaS나 멤버십: 구독 모드 체크아웃, 웹훅, 고객 포털. SaaS MVP 만드는 법과 SaaS 제품 가격 책정 방법을 참고하세요.
• 판매자에게 정산하는 마켓플레이스: 별도의, 더 규제된 설정(Stripe Connect 또는 유사 서비스)이 필요합니다. 따로 계획하세요.

Mythex 앱에 결제 추가하기

Mythex로 만든 앱의 결제는 여러분 자신의 Stripe 계정과 키를 사용합니다. 앱용 원클릭 "Stripe 연결" 기능은 없습니다. 일반적인 흐름은 다음과 같습니다.

1. Stripe 테스트 키를 받으세요.
2. STRIPE_SECRET_KEY(그리고 나중에 웹훅 비밀)를 프로젝트 시크릿에 추가하세요. /secrets, 프로젝트 설정, 또는 에이전트가 키가 필요할 때 보여 주는 시크릿 카드를 이용하면 됩니다.
3. 위와 같은 프롬프트로 에이전트에게 체크아웃을 요청하세요.
4. 미리보기에서 테스트 카드로 테스트하세요. 웹훅에는 공개 URL이 필요하므로, Stripe에 엔드포인트를 등록하기 전에 게시하세요.
5. 실서비스 키로 바꾼 뒤에는 실서비스 앱이 새 키를 반영하도록 다시 게시하세요.

자세한 내용은 문서의 Stripe로 결제 받기와 백엔드에서 웹훅 처리하기를 참고하세요.

자주 묻는 질문