Skip to main content

TossPayments 연동

TossPayments를 사용하여 신용/체크카드, 계좌이체, 가상계좌, 휴대폰 결제 등 한국의 주요 결제 수단을 지원할 수 있습니다.

사전 요구 사항

시작하기 전에 다음을 준비해주세요:
개발 중에는 테스트 모드 키를 사용하세요. 테스트 키는 test_ck_와 test_sk_ 접두사를 사용합니다. 실제 결제를 받을 준비가 되었을 때만 라이브 키로 전환하세요.

환경 변수

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

결제 흐름

TossPayments 결제 흐름은 네 단계로 구성됩니다: 장바구니 생성, 체크아웃 시작, TossPayments Widget SDK로 결제 완료, 서버 측에서 결제 승인.

웹훅 설정

Headless Commerce는 TossPayments 웹훅 이벤트를 수신하여 비동기 결제 업데이트(예: 가상계좌 입금, 취소)를 처리합니다. TossPayments 개발자센터에서 웹훅을 설정하세요:
  1. 개발자센터 → 웹훅 설정으로 이동
  2. 웹훅 URL 입력: https://api.headlesscommerce.io/v1/webhooks/tosspayments
  3. 수신할 이벤트 선택
  4. 웹훅 시크릿을 저장하고 TOSS_WEBHOOK_SECRET으로 설정

웹훅 서명 검증

TossPayments는 HMAC-SHA256을 사용하여 웹훅 페이로드에 서명합니다. 서명은 x-tosspayments-signature 헤더에 포함됩니다. Headless Commerce가 자동으로 검증하지만, 커스텀 검증이 필요한 경우:

이벤트 유형

테스트

테스트 모드 키

개발 중에는 테스트 모드 API 키를 사용하세요. 테스트 거래는 시뮬레이션되며 실제 결제가 처리되지 않습니다.

테스트 결제

테스트 모드에서 TossPayments 위젯은 시뮬레이션된 결제 흐름을 표시합니다:
  • 신용카드: 아무 카드사를 선택하고 시뮬레이션된 인증을 완료합니다
  • 계좌이체: 즉시 성공으로 시뮬레이션됩니다
  • 가상계좌: 테스트 가상계좌가 생성되며 입금을 시뮬레이션할 수 있습니다
  • 휴대폰 결제: 시뮬레이션된 모바일 결제 흐름
TossPayments 테스트 모드는 Stripe처럼 특정 테스트 카드 번호를 사용하지 않습니다. 대신, 결제 위젯 전체가 샌드박스 환경에서 동작하며 모든 결제 수단이 시뮬레이션됩니다.

로컬에서 웹훅 테스트

ngrok과 같은 터널링 도구를 사용하여 로컬 서버로 웹훅 이벤트를 전달할 수 있습니다:

오류 처리

체크아웃과 결제 승인 두 단계 모두에서 오류를 처리하세요: 체크아웃 오류:
결제 승인 오류:

실패 리다이렉트 처리

결제가 실패하면 TossPayments가 failUrl로 리다이렉트하며 오류 정보를 전달합니다:
주요 TossPayments 오류 코드:

다음 단계

웹훅

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

Stripe

글로벌 결제 수단을 위한 Stripe를 설정하세요.

API 레퍼런스

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

SDK

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