온라인 서비스에 결제 기능을 연동해야 하는 개발자라면 토스페이먼츠 개발자센터를 활용하는 것이 큰 도움이 돼요. 깔끔한 문서, 다양한 예제 코드, 테스트 환경까지 갖춰져 있어 처음 결제 연동을 시작하는 분들도 비교적 쉽게 시작할 수 있어요.
이 글에서는 토스페이먼츠 개발자센터의 구성과 주요 기능, 결제 연동을 시작하는 방법까지 안내해드릴게요.
토스페이먼츠 개발자센터 개요
개발자센터란?
토스페이먼츠 개발자센터(docs.tosspayments.com)는 토스페이먼츠 결제 API를 연동하는 개발자를 위한 공식 문서 및 도구 모음이에요. 결제 연동에 필요한 API 레퍼런스, 튜토리얼, 샘플 코드, 웹훅 설정 방법 등이 체계적으로 정리되어 있어요. 기존 PG사 문서에 비해 훨씬 현대적이고 읽기 쉽게 작성되어 있어 개발자 커뮤니티에서 높은 평가를 받고 있어요.
개발자센터 접속 방법
토스페이먼츠 개발자센터는 별도 로그인 없이 누구나 문서를 열람할 수 있어요. docs.tosspayments.com 에 접속하면 바로 확인할 수 있어요. 테스트 결제를 실행하거나 API 키를 발급받으려면 토스페이먼츠 상점 계정이 필요해요.
개발자센터 주요 구성
개발자센터는 크게 다음 섹션으로 구성되어 있어요.
- 시작하기: 결제 연동 첫 단계 안내, 테스트 환경 설정
- 결제창 연동: 웹/앱 결제창 연동 방법
- API 레퍼런스: 모든 API 엔드포인트 상세 명세
- 웹훅: 결제 이벤트 알림 수신 설정
- SDK: JavaScript, iOS, Android SDK 가이드
- 샘플 프로젝트: 언어별 예제 코드 저장소
개발자센터 시작하기 — API 키 발급
테스트 키와 라이브 키
토스페이먼츠 API를 사용하려면 먼저 API 키를 발급받아야 해요. 키는 두 종류로 나뉘어요.
- 테스트 키: 개발 환경에서 실제 결제 없이 기능을 테스트할 때 사용해요. 실제 청구가 이루어지지 않아요.
- 라이브 키: 실 운영 환경에서 실제 결제를 처리할 때 사용해요. 실제 돈이 오가므로 보안에 주의해야 해요.
두 키 모두 클라이언트 키(공개)와 시크릿 키(비공개)로 구성돼요. 시크릿 키는 절대 프론트엔드 코드에 노출하면 안 돼요.
테스트 환경 설정
토스페이먼츠는 별도 계약 없이도 테스트 키로 결제 플로우를 경험해볼 수 있어요. 개발자센터 상단의 ‘테스트 연동 시작하기’ 버튼을 클릭하면 테스트 키가 자동 발급되고, 테스트 결제창을 바로 사용해볼 수 있는 환경이 제공돼요.
결제창 연동 방법
JavaScript SDK를 이용한 기본 연동
웹에서 결제창을 연동하는 가장 기본적인 방법은 JavaScript SDK를 이용하는 거예요.
- HTML에 토스페이먼츠 SDK 스크립트 태그 추가
loadTossPayments(클라이언트 키)로 인스턴스 생성payment.requestPayment()메서드로 결제창 호출- 성공 시 결제 정보를 서버로 전달해 승인 API 호출
결제창 호출에 필요한 파라미터(금액, 주문번호, 결제 수단 등)와 성공/실패 리다이렉트 URL을 설정하면 돼요.
결제 승인 서버 처리
결제창에서 결제가 완료되면 successUrl로 리다이렉트되며 paymentKey, orderId, amount 파라미터가 전달돼요. 서버에서 이 정보를 받아 토스페이먼츠 결제 승인 API를 호출해야 최종 결제 처리가 완료돼요.
- 엔드포인트:
POST /v1/payments/confirm - 헤더: Authorization에 시크릿 키 Base64 인코딩 값 포함
- 바디: paymentKey, orderId, amount
결제 수단별 연동
토스페이먼츠는 다양한 결제 수단을 지원해요.
- 카드: 국내 모든 주요 카드사 지원
- 계좌이체: 실시간 계좌이체
- 가상계좌: 입금 확인 후 처리
- 간편결제: 토스페이, 카카오페이, 네이버페이, 삼성페이 등
- 휴대폰 결제: 통신사를 통한 소액 결제
- 상품권: 각종 상품권 결제
웹훅 설정과 활용
웹훅이란?
웹훅(Webhook)은 토스페이먼츠에서 특정 이벤트가 발생했을 때 미리 설정한 URL로 HTTP POST 요청을 보내주는 기능이에요. 결제 완료, 취소, 가상계좌 입금 확인 등의 이벤트를 실시간으로 수신해 자동 처리할 수 있어요. 상점관리자에서 웹훅 URL을 등록하고 이벤트를 선택하면 설정이 완료돼요.
주요 웹훅 이벤트
- DONE: 결제 승인 완료
- CANCELED: 결제 취소 완료
- VIRTUAL_ACCOUNT_ISSUED: 가상계좌 발급
- WAITING_FOR_DEPOSIT: 가상계좌 입금 대기
- DEPOSIT_CALLBACK: 가상계좌 입금 완료
웹훅 처리 시 주의사항
웹훅을 받을 때는 몇 가지 보안 처리가 필요해요. 첫째, 웹훅 요청의 출처가 정말 토스페이먼츠인지 검증해야 해요. 둘째, 같은 이벤트가 여러 번 전달될 수 있으니 멱등성 처리(중복 이벤트 무시)가 필요해요. 셋째, 웹훅 처리 후 200 OK 응답을 즉시 반환해야 해요. 지연 시 재시도가 발생할 수 있어요.
샘플 프로젝트 활용하기
언어별 샘플 코드
토스페이먼츠 개발자센터와 GitHub 저장소에는 다양한 언어와 프레임워크별 샘플 프로젝트가 제공돼요.
- Node.js (Express)
- Spring Boot (Java/Kotlin)
- Django (Python)
- Ruby on Rails
- PHP (Laravel)
각 샘플은 결제창 연동, 승인 API 호출, 웹훅 처리까지 전체 플로우를 보여주기 때문에 처음 연동하는 분들에게 큰 도움이 돼요.
토스페이먼츠 GitHub 저장소
토스페이먼츠의 공식 GitHub(github.com/tosspayments)에서 샘플 코드를 직접 클론해 실행해볼 수 있어요. README 파일에 따라 환경 변수를 설정하고 테스트 키를 입력하면 바로 테스트 결제를 경험해볼 수 있어요.
자주 묻는 개발 관련 질문
결제창이 뜨지 않아요
결제창이 열리지 않는 경우 가장 많은 원인은 클라이언트 키 설정 오류예요. 테스트 환경이라면 테스트 클라이언트 키를 사용하고 있는지 확인해요. 또한 결제창 호출 시 필수 파라미터(amount, orderId 등)가 빠지지 않았는지 확인해요. 브라우저 콘솔에서 에러 메시지를 확인하면 원인 파악에 도움이 돼요.
승인 API 호출이 실패해요
승인 API 호출 실패는 주로 시크릿 키 설정 오류나 Base64 인코딩 오류가 원인이에요. Authorization 헤더 형식이 Basic {시크릿 키 + ":" Base64 인코딩}인지 확인해요. 또한 paymentKey, orderId, amount가 결제창에서 반환된 값과 정확히 일치하는지 확인해요.
테스트와 실제 환경 전환 방법
개발이 완료되고 실제 서비스를 시작할 때는 테스트 키를 라이브 키로 교체하면 돼요. 상점관리자에서 라이브 키를 확인하고 환경 변수나 설정 파일에서 키 값을 바꿔주면 끝이에요. 코드 자체는 테스트와 라이브 환경에서 동일하게 작동해요.
마무리 — 토스페이먼츠 개발자센터, 잘 활용하세요
토스페이먼츠 개발자센터는 결제 연동을 처음 시작하는 분들도 쉽게 따라할 수 있도록 체계적으로 구성되어 있어요. 테스트 키로 먼저 전체 결제 플로우를 경험해보고, 샘플 프로젝트를 참고해 개발하면 빠르게 연동을 완성할 수 있어요.
막히는 부분이 있으면 개발자센터 내 FAQ, 개발자 슬랙 커뮤니티, 또는 토스페이먼츠 기술 지원팀을 통해 도움을 받아보세요. 좋은 문서와 활발한 커뮤니티가 토스페이먼츠 연동의 큰 강점이에요!