토스페이 연동가이드

이 단계에서는 가맹점 계정을 만들고 API Key를 확인해요. API Key는 결제 생성, 승인, 환불 등 모든 API 호출에서 가맹점을 인증하는 수단이라 연동을 시작하기 전에 꼭 준비해야 해요.

가맹점 계정 신청하기

먼저 계약 문의로 가맹점 가입을 신청해요. 가입이 승인되면 가맹점 계정이 발급되고, 토스페이 파트너스에 로그인해서 상점을 관리할 수 있어요.

계약이 아직 완료되지 않았다면 공용 테스트용 API Key(sk_test_w5lNQylNqa5lNQe013Nq)로 튜토리얼을 먼저 진행할 수 있어요. 다만 여러 가맹점이 함께 쓰는 Key라서 다른 가맹점의 테스트 거래가 섞일 수 있어요.

토스페이 파트너스에 로그인한 뒤 가맹점 정보 > API Key 정보에서 상점의 API Key를 확인할 수 있어요.

API Key는 테스트용과 실거래용 두 가지가 발급돼요. 둘 다 운영 환경에서 사용하는 Key이고, 어떤 Key를 쓰는지에 따라 테스트 결제와 실거래가 구분돼요.

구분	테스트용 API Key	실거래용 API Key
Key 형태	`sk_test_`로 시작	`sk_live_`로 시작
금원 이동	없음 (머니·계좌 출금 없음, 카드 승인 없음)	실제 출금과 정산이 발생해요.
용도	개발과 테스트. 승인 응답까지 실제 결제와 동일하게 확인할 수 있어요.	실제 구매자에게 서비스를 오픈할 때 사용해요.
제약	현금영수증 발급 테스트 불가	없음

튜토리얼에서는 테스트용 API Key를 사용해요. 실거래용 API Key로 전환하는 시점과 주의사항은 6. 테스트와 라이브 전환하기에서 다뤄요.

API Key가 유출되지 않도록 주의하세요. API Key가 외부에 노출되면 원치 않는 결제 생성이나 환불이 발생해서 상점에 금전적 손실이 생길 수 있어요. API Key는 서버에만 보관하고, 웹 페이지나 앱 코드처럼 외부에서 볼 수 있는 곳에 넣지 마세요.

API Key를 준비했다면 이제 첫 결제를 만들 차례예요. 2. 결제 생성하기로 이동하세요.