토스페이먼츠 API 수수료와 연동 가이드 2026 (우대 0.4%)

최종 수정일: 2026년 08월 11일

토스페이먼츠 API는 REST 방식의 국내 PG 결제 인터페이스로, 카드·계좌이체·가상계좌부터 카카오페이·네이버페이 같은 간편결제까지 하나의 연동으로 처리합니다. 수수료는 공개 표준 요율이 아니라 업종·거래량에 따라 계약 시 개별 산정되며, 연매출 30억 원 이하 가맹점은 2026년 기준 신용카드 0.4~1.45%의 우대 수수료율을 적용받습니다.

연동은 가맹점 심사 → API 키 발급 → 샌드박스 테스트 → 프로덕션 전환 순서로 진행되고, Secret Key는 반드시 서버에서만 관리해야 합니다.

온라인 비즈니스를 새로 시작하거나 기존 서비스를 확장할 때 결제 시스템 구축은 생각보다 훨씬 큰 변수입니다. 결제 경험이 흔들리면 고객 만족도도 같이 흔들리고, 그게 그대로 매출로 이어지기 때문입니다. 이런 상황에서 많이 거론되는 솔루션이 토스페이먼츠 API입니다. 토스페이먼츠가 제공하는 이 API는 개발자가 웹사이트나 앱에 결제 기능을 비교적 간단하게 붙일 수 있도록 돕는 핵심 도구입니다.

이 글에서는 토스페이먼츠 API의 기본 개념부터 주요 기능, 수수료 체계, 실제 연동 방법과 테스트 과정까지 한 번에 정리해 드리겠습니다. 결제 붙이기 전에 “뭘 먼저 확인해야 하지?” 같은 질문이 있으셨다면, 이 글이 기준점이 될 수 있습니다.

토스페이먼츠 API 소개

토스페이먼츠 API란 무엇인가요?

온라인 상점에서 물건을 구매하거나 서비스를 이용할 때 신용카드, 계좌이체, 간편결제 같은 수단으로 결제를 합니다. 이 결제 과정의 기술적 기반을 담당하는 것이 토스페이먼츠의 결제 인터페이스입니다.

API는 Application Programming Interface의 줄임말입니다. 서로 다른 프로그램이 약속된 방식으로 연결되는 통로라고 이해하시면 됩니다. 즉, 이 인터페이스를 활용하면 개발자가 결제 시스템을 처음부터 직접 만들 필요가 줄어듭니다. 토스페이먼츠가 구축해 둔 결제 기능을 가져다 쓸 수 있기 때문입니다. 그만큼 개발 시간과 비용을 줄이고, 서비스 기획이나 운영 같은 본업에 집중하기가 수월해집니다.

토스페이먼츠는 비바리퍼블리카가 LG유플러스의 전자지급결제(PG) 사업 부문을 인수해 2020년 8월 출범한 전자금융업체입니다. 전자금융업 등록을 마쳤고, 전자지급결제대행업(PG업)과 결제대금예치업 라이선스도 보유하고 있습니다. 이런 제도적 기반은 가맹점과 소비자 모두에게 “거래가 제도권 안에서 관리된다”는 신뢰를 주는 요소입니다. 국내 온라인 결제 시장의 주요 PG사 중 하나로 자리 잡았고, 카카오페이, 네이버페이, 페이코 등 주요 간편결제 연동도 지원합니다.

이 결제 시스템은 RESTful API 방식으로 설계되어 있습니다. 웹 주소처럼 정해진 규칙으로 요청하고 응답을 받는 구조라고 보시면 됩니다. HTTP 기반으로 GET, POST, PUT, DELETE 같은 표준 명령을 사용합니다. 개발자 입장에서는 웹 개발 흐름과 비슷하게 붙일 수 있어 진입 장벽이 낮습니다.

데이터는 JSON 형태로 주고받습니다. 사람이 봐도 구조가 단순해서 처리하기 편한 편입니다. 보안은 Secret Key를 HTTP Authorization 헤더에 포함하는 Basic 인증 방식을 사용합니다. 민감한 결제 정보가 오가는 만큼, 키 관리가 실무에서 가장 먼저 챙겨야 할 포인트입니다.

API 기반 결제 시스템은 기존 모듈 방식보다 개발 편의성과 확장성이 높고, 모바일 환경의 사용자 경험 개선에도 유리한 구조입니다.

전자지급결제대행업은 전자금융거래법의 규제를 받습니다. 전자금융거래법 제2조 제19호는 전자지급결제대행을 전자적 방법으로 지급결제정보를 송신·수신하거나 그 대가의 정산을 대행·매개하는 것으로 정의합니다. 이 정의 자체가 “단순 기술 제공”을 넘어 법적 책임이 붙는 영역이라는 뜻입니다.

실무에서 결제 연동을 맡아보면, 법무나 컴플라이언스 쪽과 같이 조항을 확인하는 일이 생각보다 자주 생깁니다. 이런 근거가 탄탄해야 가맹점도, 소비자도 안심하고 거래를 이어갈 수 있습니다.

토스페이먼츠 API의 주요 기능은 무엇인가요?

이 결제 API는 결제 처리만 하는 수준이 아닙니다. 결제 내역 조회, 주문 취소 및 환불, 정산, 가상 계좌 발급, 빌링(자동결제), 본인인증까지 결제 흐름에서 필요한 기능을 폭넓게 제공합니다. 기능이 각각 독립 API로 제공되기 때문에, 필요한 것만 골라 붙이거나 조합해서 쓰는 방식도 가능합니다.

주요 기능은 다음과 같습니다.

• 일반결제 API (Payment API) 일반 상품 및 서비스 결제 처리
• 빌링 API (Billing API) 구독형 서비스 자동 결제에 활용
• 현금영수증 API 현금영수증 발행 지원
• 에스크로 API 구매대금 예치 기반 안전거래 지원
• 본인인증 API 회원가입 등 본인 확인 기능

UI 통합 방식도 두 가지를 제공합니다. 위젯(Widget) 방식은 결제창 디자인과 흐름을 서비스에 맞게 더 세밀하게 조정할 수 있습니다. 결제창(Payment Window) 방식은 토스페이먼츠 표준 결제창을 바로 쓰는 형태라 개발 속도가 빠릅니다. “브랜드 경험을 맞출 것인가, 빠르게 붙일 것인가”에서 선택이 갈리는 지점입니다.

보안은 결제에서 빠질 수 없습니다. 토스페이먼츠는 PCI-DSS Level 1 인증을 획득했고, 3D Secure 인증으로 카드 결제 시 추가 본인 인증 절차를 지원합니다. 카드 도용 같은 부정 거래를 줄이는 데 도움이 됩니다.

안정성과 속도도 강점으로 자주 언급됩니다. 안정적인 응답 속도와 높은 가용성을 유지하고 있습니다. 구체적인 SLA 수준은 계약 조건에 따라 달라집니다. 결제에서 1~2초 지연이 이탈로 이어지는 업종이라면 이 부분은 체감이 큽니다.

Webhook(웹훅)으로 결제 상태 변경, 가상 계좌 입금 완료, 정산 완료 같은 이벤트를 실시간 전달합니다. 폴링 방식보다 서버 부하를 줄이고, 후속 처리를 빠르게 붙일 수 있습니다.

거래 기록 보존은 전자금융거래법 제22조에 따라 최소 5년간 보관하도록 규정되어 있습니다. 분쟁이 생겼을 때 거래 기록이 깔끔하게 남아 있으면, 해결 속도가 달라집니다.

토스페이먼츠 결제 API

이 결제 시스템은 신용카드, 체크카드, 계좌이체, 가상 계좌, 휴대폰 소액결제는 물론 토스페이, 카카오페이, 네이버페이 같은 간편결제까지 폭넓게 지원합니다. 가맹점 입장에서는 여러 PG를 따로 계약하고 붙이는 번거로움을 줄일 수 있다는 점이 큽니다.

결제 과정은 보통 3단계로 이해하면 됩니다. 결제 요청(Payment Request)에서 고객이 결제 수단을 선택하고 정보를 입력합니다. 결제 승인(Payment Approval)에서 토스페이먼츠가 카드사나 은행에 승인을 요청합니다. 결제 완료(Payment Confirmation)에서 승인 결과가 가맹점 서버로 전달되고 고객에게 성공 여부가 표시됩니다.

해당 결제 인터페이스는 SDK도 제공합니다. JavaScript(Node.js), iOS(Swift), Android(Kotlin, Java) 등 주요 환경을 지원합니다. SDK를 쓰면 API 호출 로직을 직접 다 짜는 부담이 줄고, 구현 속도도 빨라집니다.

카드 정보는 토큰화(Tokenization) 방식으로 처리됩니다. 실제 카드 번호 대신 토큰을 사용해 결제를 진행하는 구조라, 가맹점 서버에 민감 정보가 남지 않도록 설계됩니다.

토큰화는 카드 정보 유출 위험을 줄이는 대표적인 방식이며, PCI-DSS 준수 과정에서 핵심 기술로 다뤄집니다.

가상 계좌처럼 입금까지 시간이 걸리는 결제는 비동기 처리와 Webhook 조합이 특히 유용합니다. 입금 완료 알림을 받아서 주문 상태를 자동으로 바꾸는 흐름을 만들 수 있기 때문입니다.

해외 카드 결제와 다중 통화 결제도 지원합니다. USD, JPY, EUR, CNY 등 주요 통화 결제가 가능하고 환율이 실시간 적용됩니다. 해외 고객을 받는 서비스라면 체크할 만한 기능입니다.

토스페이먼츠 API 환불

이 환불 기능은 쇼핑몰 운영에서 자주 마주치는 취소, 환불을 처리하는 핵심 기능입니다. 취소 API(Cancel API)로 전액 또는 부분 취소를 구현할 수 있습니다. 결제 수단에 따라 즉시 처리되기도 하고 시간이 걸리기도 하니, 고객 안내 문구까지 같이 설계해 두는 편이 안전합니다.

환불은 보통 3단계로 진행됩니다. 취소 요청(Cancel Request)에서 취소 사유와 금액을 API로 전달합니다. 취소 승인(Cancel Approval)에서 PG, 카드사, 은행 쪽 승인 절차가 진행됩니다. 취소 완료(Cancel Confirmation)에서 환불 완료 알림이 가맹점 서버로 전달되고 고객에게 결과가 안내됩니다.

신용카드 환불은 결제 당일 취소(승인 취소)와 익일 이후 취소(매입 취소)로 나뉩니다. 매입 취소는 카드사 정책에 따라 3~7영업일이 걸릴 수 있습니다. 계좌이체, 가상 계좌 환불은 보통 1~3영업일이 소요됩니다.

해당 API는 부분 환불도 지원합니다. 여러 번 나눠 환불할 수는 있지만, 총 환불 금액이 최초 결제 금액을 넘을 수는 없습니다. 반품이 잦은 카테고리라면 이 기능은 거의 필수입니다.

환불 정책은 「전자상거래 등에서의 소비자보호에 관한 법률」을 따라야 합니다. 제17조(청약철회등)에 따라 소비자는 재화를 공급받은 날부터 7일 이내 청약철회가 가능하고, 제18조에 따라 판매자는 재화를 반환받은 날부터 3영업일 이내에 대금을 환급해야 합니다.

환불 수수료는 계약 조건에 따라 달라질 수 있으나, 통상 환불 건에 별도 수수료가 붙지 않는 경우가 많습니다. 다만 부분 환불은 최초 거래 수수료 정산이 조정될 수 있으니 계약서를 확인해야 합니다. 환불 가능 기간은 결제 수단별로 다르게 제한됩니다. 카드와 계좌 계열은 비교적 길고 휴대폰 소액결제는 짧은 편이며, 정확한 기간은 개발자센터 문서에서 확인하셔야 합니다.

환불 과정에서 문제가 생기면 이 시스템은 에러 코드와 메시지를 제공합니다. 이미 취소된 거래, 취소 가능 금액 초과, 카드사/은행 시스템 오류 같은 케이스별 가이드가 포함되어 있어 원인 파악이 빠른 편입니다.

토스페이먼츠 API 수수료는 어떻게 책정되나요?

가맹점이라면 결제 수수료가 매출에 직접 영향을 준다는 점을 피할 수 없습니다. 이 결제 시스템의 수수료는 결제 수단, 거래 금액, 업종, 그리고 계약 조건에 따라 달라집니다. 그래서 “대략 이 정도겠지”로 접근하면 나중에 정산에서 체감이 크게 옵니다. 계약 전에는 반드시 수수료표와 정산 주기를 같이 확인하셔야 합니다.

토스페이먼츠 API 수수료 요약

수수료는 결제 금액의 일정 비율로 책정되며, 결제 수단과 업종·거래량에 따라 달라집니다. 공개된 표준 요율이 아니라 계약 시 개별 산정되는 구조이므로, 정확한 수치는 토스페이먼츠 공식 요금 안내와 계약서에서 직접 확인하셔야 합니다. 거래량과 업종에 따라 협상 여지가 생기기도 합니다.

연매출 30억 원 이하 영세·중소 가맹점에는 여신전문금융업감독규정에 따라 우대 수수료율이 적용됩니다. 2026년 기준 신용카드는 연매출 3억 원 이하 0.4%, 3억 초과 5억 이하 1.0%, 5억 초과 10억 이하 1.15%, 10억 초과 30억 이하 1.45%이며, 체크카드는 0.15%~1.15%입니다. PG사를 통해 카드 결제를 받는 하위 가맹점에도 동일하게 적용됩니다.

추가 비용도 체크해야 합니다. 즉시 정산, 가상 계좌 발급, 해외 카드 결제는 기본 수수료 외에 별도 요금이 붙을 수 있습니다. 이 금액들에는 부가가치세(VAT)가 별도로 붙을 수 있으니, 실제 비용 계산에서는 VAT 포함 기준으로 보시는 편이 안전합니다.

정산 주기는 보통 D+2 또는 D+7이 적용되며 업종과 위험도에 따라 달라질 수 있습니다. 즉시 정산(D+0)은 현금 흐름에는 유리하지만, 그만큼 비용이 늘어납니다. “빠른 정산이 필요한 상황인지”를 먼저 정리하고 선택하시는 게 좋습니다.

토스페이먼츠 API 연동

토스페이먼츠 API 연동 가이드

이 연동 가이드는 토스페이먼츠 결제 시스템을 서비스에 통합하기 위한 실무 문서입니다. 기술 사양만 나열하는 문서가 아니라, 단계별 절차와 코드 예시, 보안 요구사항까지 포함되어 있어 연동 작업의 기준점으로 쓰기 좋습니다.

연동 과정은 보통 아래 흐름으로 진행됩니다.

1. 가맹점 가입, 심사 가입 후 비즈니스 모델 적합성 심사 통과 필요
2. API 키 발급 Client Key, Secret Key 발급 후 보안 관리 필수
3. 개발 환경 설정 서버 환경이 요구사항을 충족하도록 설정
4. SDK 또는 API 통합 SDK 사용 또는 REST API 직접 호출로 결제 기능 구현
5. 테스트 환경에서 검증 샌드박스에서 기능 정상 동작 여부 확인
6. 실서비스 전환, 운영 프로덕션 전환 후 모니터링과 운영 체계 구축

기술 요구사항도 같이 챙겨야 합니다.

1. 모든 통신은 HTTPS(TLS 1.2 이상) 기반으로 구성
2. 가맹점 서버 IP를 화이트리스트로 등록해 접근 통제
3. Webhook 사용 시 공인 IP와 도메인 필요
4. JSON 처리 라이브러리(파서 등) 서버 환경에 설치 필요

공식 개발자 문서에는 REST API 레퍼런스, SDK 사용법, 샘플 코드, FAQ, 에러 코드 등이 포함되어 있습니다. 한국어와 영어 문서가 함께 제공되는 점도 실무에서는 편합니다.

API 인증은 Basic 인증 방식입니다. 형식은 “Basic {Base64(SecretKey:)}” 형태로 안내됩니다. Secret Key는 클라이언트(브라우저, 앱)에 노출되면 안 됩니다. 서버에서만 관리하고 호출해야 합니다.

샌드박스(Sandbox) 환경은 실제 돈이 오가지 않는 테스트 공간입니다. 테스트용 카드 번호와 계좌 정보가 제공되기 때문에, 실제와 유사한 흐름으로 검증할 수 있습니다.

보안 권장사항도 정리해 두겠습니다.

1. Secret Key는 환경 변수 또는 보안 저장소에 보관
2. 결제 금액 검증은 반드시 서버에서 수행
3. Webhook 수신 시 서명(Signature) 검증으로 위변조 방지
4. 로그에 카드 번호, 비밀번호 등 민감 정보 기록 금지

기술 지원 채널도 운영됩니다. 포럼, 커뮤니티, 이메일/채팅 지원, 전화 상담, 세미나/웨비나 등으로 구성되는 경우가 많고, 문의 채널별로 응답 시간이 다르게 안내됩니다.

토스페이먼츠 API 테스트

이 테스트 과정은 실제 돈이 오가기 전에 기능, 안정성, 보안을 검증하는 단계입니다. 샌드박스에서 테스트 데이터를 활용해 진행합니다. 결제는 한 번 장애가 나면 고객 불만이 바로 터지는 영역이라, 테스트는 “해도 되고 안 해도 되는 것”이 아니라 필수입니다.

토스페이먼츠는 프로덕션(Production)과 분리된 테스트 환경을 제공합니다. 테스트 API 엔드포인트가 별도 URL이라 실수로 실결제를 만들 위험을 줄일 수 있습니다.

정상 결제 성공은 물론 잔액 부족, 한도 초과 같은 실패 시나리오도 재현할 수 있도록 구성되어 있습니다.

주요 테스트 시나리오

테스트에 사용할 카드 번호와 계좌 정보는 토스페이먼츠 개발자센터 공식 문서에서 확인하실 수 있습니다. 시나리오별 재현 방법도 함께 안내되어 있습니다.
주요 테스트 시나리오는 아래 정도는 기본으로 잡고 가는 편이 좋습니다.

1. 정상 결제 승인 확인
2. 잔액 부족, 한도 초과, 카드 정지 등 실패 처리 확인
3. 전체 취소, 부분 취소 동작 확인
4. 가상 계좌 발급과 입금 처리 확인
5. Webhook 수신 후 후속 처리 로직 검증
6. 타임아웃, 네트워크 오류 상황에서의 안정성 확인

테스트 환경 응답은 실제보다 빠를 수 있습니다. 실제 성능을 보려면 프로덕션 환경에서 별도 성능 테스트를 진행해야 합니다. 특히 트래픽이 몰리는 업종이라면 부하 테스트(Load Testing)와 스트레스 테스트(Stress Testing)까지 같이 보셔야 합니다. PG가 빠르더라도 가맹점 서버가 느리면 결제는 결국 느려집니다.

테스트 도구로는 API 콘솔, Postman Collection, 테스트 결제창 등이 제공됩니다. 이런 도구를 활용하면 기능 검증 속도가 확실히 빨라집니다.

실서비스 전환 전 최종 점검도 빠뜨리면 안 됩니다.

1. 프로덕션 API 키로 변경 완료
2. 테스트용 코드와 로그 제거
3. 에러 모니터링 체계 구축
4. 고객 지원 프로세스 수립
5. 백업, 복구 계획 마련
6. 보안 취약점 점검 완료

지금까지 토스페이먼츠 API를 기능, 수수료, 연동, 테스트 관점에서 정리해 봤습니다. 결제는 “붙이면 끝”이 아니라 운영까지 포함해서 설계해야 하는 영역입니다. 연동 자체는 문서대로 하면 되지만, 수수료와 정산, 환불 정책, 보안과 장애 대응까지 같이 챙겨야 실제 매출 구간에서 흔들리지 않습니다.

FAQ

Q1: 토스페이먼츠 API는 어떤 결제 수단을 지원하나요?
A1: 토스페이먼츠 API는 신용카드, 체크카드, 계좌이체, 가상계좌, 휴대폰 소액결제 등 기본 결제 수단은 물론 토스페이, 카카오페이, 네이버페이, 페이코 등 국내 주요 간편결제까지 지원합니다. 해외 카드 결제와 다중 통화 결제도 가능해 글로벌 비즈니스에도 활용할 수 있습니다.

Q2: 토스페이먼츠 API 연동 시 보안은 어떻게 강화되나요?
A2: PCI-DSS Level 1 인증 기반으로 국제 카드 결제 보안 표준을 준수하며, 3D Secure 인증을 통해 추가 보안 계층을 제공합니다. 카드 정보는 토큰화 방식으로 처리되어 가맹점 서버에 실제 카드 번호가 저장되지 않도록 설계됩니다. API 호출은 Secret Key 기반 Basic 인증으로 보호되며, Secret Key는 서버에서만 관리해야 합니다.

Q3: 토스페이먼츠 API를 통한 환불 처리 과정은 어떻게 되나요?
A3: 환불은 취소 API(Cancel API)로 처리하며, 취소 요청-취소 승인-취소 완료의 3단계로 진행됩니다. 신용카드는 당일 취소 시 승인 취소로 빠르게 처리되지만, 익일 이후 취소는 매입 취소로 처리되어 카드사 정책에 따라 3~7영업일이 걸릴 수 있습니다. 계좌이체 및 가상계좌 환불은 보통 1~3영업일이 소요됩니다. 부분 환불도 지원하며 환불 가능 기간은 결제 수단별로 다릅니다.

Q4: 토스페이먼츠 API 수수료는 어떻게 책정되며, 중소가맹점 혜택이 있나요?
A4: 수수료는 결제 수단, 거래 금액, 업종, 계약 조건에 따라 달라지며 계약 시 개별 산정됩니다. 연매출 30억 원 이하 영세·중소가맹점은 우대 수수료율이 적용되며, 2026년 기준 연매출 3억 원 이하는 신용카드 0.4%, 체크카드 0.15%입니다. PG사 하위 가맹점에도 동일하게 적용됩니다. 즉시 정산, 가상계좌 발급, 해외 카드 결제는 추가 수수료가 발생할 수 있습니다.

Q5: 토스페이먼츠 API 연동 후 테스트는 어떻게 진행해야 하나요?
A5: 토스페이먼츠는 샌드박스(Sandbox) 테스트 환경을 제공하며, 테스트용 카드 번호와 계좌 정보를 활용해 정상 결제, 실패, 취소, 환불, Webhook 수신 등 다양한 시나리오를 검증할 수 있습니다. API 콘솔, Postman Collection, 테스트 결제창 같은 도구를 활용해 기능 안정성과 보안을 점검한 뒤 프로덕션으로 전환하는 흐름이 일반적입니다.

※ 2026년 8월 기준 공식 개발자 문서와 금융위원회 자료를 확인해 작성했습니다. 수수료율과 정산 정책은 변경될 수 있으니 계약 전 공식 안내를 다시 확인하시기 바랍니다.