토스페이 연동 시작하기
이 튜토리얼은 토스페이 온라인 결제를 처음 연동하는 개발자를 위한 문서예요. 구매자가 매번 인증하는 일반 결제(단건 결제)를 기준으로, 순서대로 따라 하면 결제 생성부터 구매자 인증, 결제 승인, 라이브 전환까지 첫 결제를 완주할 수 있어요. 실제 출금이 일어나지 않는 테스트용 API Key로 진행하니 부담 없이 시작해도 돼요.
결제가 완료되기까지의 흐름
토스페이 결제는 세 주체가 참여해요. 가맹점 서버가 결제를 생성하면 구매자가 토스 앱에서 결제 수단을 선택해 인증하고, 토스 서버가 결제를 완료 처리한 뒤 결과를 가맹점 서버에 알려줘요. 전체 흐름은 다음 그림과 같아요.
미리 준비할 것
튜토리얼을 진행하려면 다음이 필요해요.
- 계약을 완료했다면 토스페이 파트너스에서 발급받은 테스트용 API Key를 준비하세요. 계약 전이라면 공용 테스트용 API Key(
sk_test_w5lNQylNqa5lNQe013Nq)로도 따라 할 수 있어요. - 결제 생성 API를 호출하고 결제 결과 콜백을 받을 가맹점 서버가 필요해요. 콜백 URL은 외부에서 접근할 수 있어야 해요.
- 구매자를 토스페이 결제창으로 이동시킬 결제 화면(웹 페이지 또는 앱의 WebView)이 필요해요.
핵심 용어
튜토리얼 전체에서 반복해서 쓰는 용어예요.
| 용어 | 설명 |
|---|---|
payToken | 결제 건 하나를 구분하는 토스 고유 값이에요. 승인, 환불, 상태 조회 등 모든 후속 처리에 사용해요. |
checkoutPage | 구매자가 결제를 진행하는 토스페이 웹 페이지 URL이에요. 결제를 생성하면 응답으로 받아요. |
autoExecute | 구매자 인증이 끝났을 때 토스가 결제를 자동으로 승인할지 결정하는 옵션이에요. 값에 따라 연동 방식이 달라져요. |
일반 결제 연동 단계
여섯 단계로 진행해요. 각 단계는 이전 단계의 결과를 이어받으니 순서대로 읽는 것을 추천해요.
1. 개발 준비하기
가맹점 계정과 테스트용·실거래용 API Key를 준비해요.
2. 결제 생성하기
결제 생성 API를 호출하고 checkoutPage와 payToken을 받아요.
3. 결제창 연결하기
구매자를 checkoutPage로 보내 결제 수단 선택과 인증을 진행해요.
4. 인증 결과 처리하기
retUrl로 돌아온 구매자의 인증 결과를 확인해요.
5. 결제 승인과 콜백 처리하기
결제를 최종 승인하고 콜백으로 완료를 확인해요.
6. 테스트와 라이브 전환하기
시나리오별로 점검하고 실거래용 API Key로 전환해요.
연동 전에 결제를 먼저 경험해 보고 싶다면 데모 체험하기에서 실제 결제 흐름을 미리 볼 수 있어요.
AI 도구로 연동을 개발하고 있다면 LLM이 읽기 좋은 /llms.txt를 제공해요. 활용 방법은 AI 도구로 연동하기를 참고하세요.
다른 결제 방식 연동하기
구독, 멤버십처럼 반복 결제가 필요하다면 빌링키 기반의 자동 결제를 연동하세요. 자동 결제 튜토리얼에서 빌링키 발급부터 자동 결제 승인까지 안내해요.