Stripe 연동
Stripe를 결제 수단으로 사용하여 신용카드, Apple Pay, Google Pay 및 40개 이상의 결제 수단을 전 세계적으로 지원할 수 있습니다.사전 요구 사항
시작하기 전에 다음을 준비해주세요:- Stripe 계정 — 계정이 없다면 stripe.com에서 가입하세요
- Stripe Dashboard에서 Stripe API 키 확인
- 최소 하나 이상의 상품이 등록된 Headless Commerce 스토어
개발 중에는 테스트 모드 키(
sk_test_... / pk_test_...)를 사용하세요. 실제 결제를 받을 준비가 되었을 때만 라이브 키로 전환하세요.환경 변수
API 서버에 다음 환경 변수를 추가하세요:결제 흐름
Stripe 결제 흐름은 네 단계로 구성됩니다: 장바구니 생성, 체크아웃 시작, 클라이언트에서 결제 확인, 웹훅 처리.웹훅 설정
Headless Commerce는 Stripe 웹훅 이벤트를 수신하여 주문 및 결제 상태를 동기화합니다. Stripe Dashboard에서 웹훅을 설정하세요:- Stripe Dashboard에서 Developers → Webhooks로 이동
- Add endpoint 클릭
- 웹훅 URL 입력:
https://api.headlesscommerce.io/v1/webhooks/stripe - 다음 이벤트를 선택:
payment_intent.succeededpayment_intent.payment_failedcharge.refundedcharge.dispute.created
- Signing secret을 복사하여
STRIPE_WEBHOOK_SECRET으로 설정
이벤트 처리
환불
Admin API를 통해 전액 또는 부분 환불을 처리할 수 있습니다:테스트
테스트 모드 키
개발 중에는 항상 테스트 모드 API 키를 사용하세요. 테스트 키로 생성된 거래는 실제 결제 네트워크를 사용하지 않습니다.테스트 카드 번호
테스트 모드에서 다음 카드 번호를 사용할 수 있습니다:
만료일은 미래 날짜, CVC는 아무 3자리 숫자, 우편번호는 아무 값이나 사용할 수 있습니다.
로컬에서 웹훅 테스트
Stripe CLI를 사용하여 로컬 개발 서버로 웹훅 이벤트를 전달할 수 있습니다:오류 처리
프론트엔드에서 결제 오류를 적절히 처리하세요:confirmPayment() 이후 발생할 수 있는 주요 Stripe 오류:
다음 단계
웹훅
모든 웹훅 이벤트와 페이로드 형식을 확인하세요.
TossPayments
한국 결제 수단을 위한 TossPayments를 설정하세요.
API 레퍼런스
모든 체크아웃 및 결제 엔드포인트를 살펴보세요.
SDK
전체 SDK 레퍼런스와 모든 리소스 및 메서드를 확인하세요.