TossPayments 연동
TossPayments를 사용하여 신용/체크카드, 계좌이체, 가상계좌, 휴대폰 결제 등 한국의 주요 결제 수단을 지원할 수 있습니다.사전 요구 사항
시작하기 전에 다음을 준비해주세요:- TossPayments 계정 — 계정이 없다면 tosspayments.com에서 가입하세요
- TossPayments 개발자센터에서 API 키 확인
- 최소 하나 이상의 상품이 등록된 Headless Commerce 스토어
개발 중에는 테스트 모드 키를 사용하세요. 테스트 키는
test_ck_와 test_sk_ 접두사를 사용합니다. 실제 결제를 받을 준비가 되었을 때만 라이브 키로 전환하세요.환경 변수
API 서버에 다음 환경 변수를 추가하세요:결제 흐름
TossPayments 결제 흐름은 네 단계로 구성됩니다: 장바구니 생성, 체크아웃 시작, TossPayments Widget SDK로 결제 완료, 서버 측에서 결제 승인.웹훅 설정
Headless Commerce는 TossPayments 웹훅 이벤트를 수신하여 비동기 결제 업데이트(예: 가상계좌 입금, 취소)를 처리합니다. TossPayments 개발자센터에서 웹훅을 설정하세요:- 개발자센터 → 웹훅 설정으로 이동
- 웹훅 URL 입력:
https://api.headlesscommerce.io/v1/webhooks/tosspayments - 수신할 이벤트 선택
- 웹훅 시크릿을 저장하고
TOSS_WEBHOOK_SECRET으로 설정
웹훅 서명 검증
TossPayments는 HMAC-SHA256을 사용하여 웹훅 페이로드에 서명합니다. 서명은x-tosspayments-signature 헤더에 포함됩니다.
Headless Commerce가 자동으로 검증하지만, 커스텀 검증이 필요한 경우:
이벤트 유형
테스트
테스트 모드 키
개발 중에는 테스트 모드 API 키를 사용하세요. 테스트 거래는 시뮬레이션되며 실제 결제가 처리되지 않습니다.테스트 결제
테스트 모드에서 TossPayments 위젯은 시뮬레이션된 결제 흐름을 표시합니다:- 신용카드: 아무 카드사를 선택하고 시뮬레이션된 인증을 완료합니다
- 계좌이체: 즉시 성공으로 시뮬레이션됩니다
- 가상계좌: 테스트 가상계좌가 생성되며 입금을 시뮬레이션할 수 있습니다
- 휴대폰 결제: 시뮬레이션된 모바일 결제 흐름
TossPayments 테스트 모드는 Stripe처럼 특정 테스트 카드 번호를 사용하지 않습니다. 대신, 결제 위젯 전체가 샌드박스 환경에서 동작하며 모든 결제 수단이 시뮬레이션됩니다.
로컬에서 웹훅 테스트
ngrok과 같은 터널링 도구를 사용하여 로컬 서버로 웹훅 이벤트를 전달할 수 있습니다:오류 처리
체크아웃과 결제 승인 두 단계 모두에서 오류를 처리하세요: 체크아웃 오류:실패 리다이렉트 처리
결제가 실패하면 TossPayments가failUrl로 리다이렉트하며 오류 정보를 전달합니다:
다음 단계
웹훅
모든 웹훅 이벤트와 페이로드 형식을 확인하세요.
Stripe
글로벌 결제 수단을 위한 Stripe를 설정하세요.
API 레퍼런스
모든 체크아웃 및 결제 엔드포인트를 살펴보세요.
SDK
전체 SDK 레퍼런스와 모든 리소스 및 메서드를 확인하세요.