Skip to main content

Stripe 연동

Stripe를 결제 수단으로 사용하여 신용카드, Apple Pay, Google Pay 및 40개 이상의 결제 수단을 전 세계적으로 지원할 수 있습니다.

사전 요구 사항

시작하기 전에 다음을 준비해주세요:
  • Stripe 계정 — 계정이 없다면 stripe.com에서 가입하세요
  • Stripe Dashboard에서 Stripe API 키 확인
  • 최소 하나 이상의 상품이 등록된 Headless Commerce 스토어
개발 중에는 테스트 모드 키(sk_test_... / pk_test_...)를 사용하세요. 실제 결제를 받을 준비가 되었을 때만 라이브 키로 전환하세요.

환경 변수

API 서버에 다음 환경 변수를 추가하세요:
프론트엔드 애플리케이션에는 퍼블리셔블 키를 추가하세요:
STRIPE_SECRET_KEY와 STRIPE_WEBHOOK_SECRET은 절대 클라이언트에 노출하지 마세요. 서버 측에서만 사용해야 합니다.

결제 흐름

Stripe 결제 흐름은 네 단계로 구성됩니다: 장바구니 생성, 체크아웃 시작, 클라이언트에서 결제 확인, 웹훅 처리.

웹훅 설정

Headless Commerce는 Stripe 웹훅 이벤트를 수신하여 주문 및 결제 상태를 동기화합니다. Stripe Dashboard에서 웹훅을 설정하세요:
  1. Stripe Dashboard에서 Developers → Webhooks로 이동
  2. Add endpoint 클릭
  3. 웹훅 URL 입력: https://api.headlesscommerce.io/v1/webhooks/stripe
  4. 다음 이벤트를 선택:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • charge.refunded
    • charge.dispute.created
  5. Signing secret을 복사하여 STRIPE_WEBHOOK_SECRET으로 설정

이벤트 처리

환불

Admin API를 통해 전액 또는 부분 환불을 처리할 수 있습니다:
환불은 Stripe를 통해 자동으로 처리되며 주문 상태가 그에 따라 업데이트됩니다.

테스트

테스트 모드 키

개발 중에는 항상 테스트 모드 API 키를 사용하세요. 테스트 키로 생성된 거래는 실제 결제 네트워크를 사용하지 않습니다.

테스트 카드 번호

테스트 모드에서 다음 카드 번호를 사용할 수 있습니다: 만료일은 미래 날짜, CVC는 아무 3자리 숫자, 우편번호는 아무 값이나 사용할 수 있습니다.

로컬에서 웹훅 테스트

Stripe CLI를 사용하여 로컬 개발 서버로 웹훅 이벤트를 전달할 수 있습니다:

오류 처리

프론트엔드에서 결제 오류를 적절히 처리하세요:
confirmPayment() 이후 발생할 수 있는 주요 Stripe 오류:

다음 단계

웹훅

모든 웹훅 이벤트와 페이로드 형식을 확인하세요.

TossPayments

한국 결제 수단을 위한 TossPayments를 설정하세요.

API 레퍼런스

모든 체크아웃 및 결제 엔드포인트를 살펴보세요.

SDK

전체 SDK 레퍼런스와 모든 리소스 및 메서드를 확인하세요.