문서
토스페이먼츠의 Open API 생태계
허지훈 토스 · 토스 기술 블로그
AI 핵심 요약
20만 개 이상의 가맹점이 사용하는 결제 API를 장기간 안정적으로 운영하기 위해 토스페이먼츠는 API를 단순한 기능이 아니라 지속적으로 관리해야 할 인프라로 바라봅니다. 인터페이스는 리소스 중심 경로와 일관된 JSON 객체를 사용하고, 비동기 결과는 웹훅으로 전달하며 Exponential Backoff 재전송을 적용합니다. 개발자 경험을 위해 OpenAPI Specification 기반 문서 자동화, 브라우저 샌드박스, 라이브와 분리된 테스트 환경, 에러 재현·로그 조회 도구를 제공하고 API 버저닝으로 기존 연동을 보호합니다. API Key와 웹훅 서명, TLS, JWE 암호화, Rate Limiting을 함께 적용하며, 장기적인 API 품질은 일관된 설계와 개발·운영 전 과정의 지원으로 만들어진다는 점을 보여줍니다.
- 리소스 중심 경로와 재사용 가능한 JSON 객체를 적용하면 API 간 구조가 일관되어 연동 학습과 코드 중복을 줄일 수 있습니다.
- 비동기 작업은 웹훅으로 알리고, 실패 재전송에는 Exponential Backoff를 적용해 수신 서비스의 회복 시간을 확보합니다.
- OpenAPI Specification을 서버 스펙에서 자동 생성하고 문서와 동기화하면 문서와 실제 동작의 불일치를 줄일 수 있습니다.
- 테스트 환경은 라이브와 같은 코드 흐름을 유지하되 외부 결제 호출을 Mock으로 대체하고, 환경과 트래픽을 분리하는 방식으로 구성할 수 있습니다.
- API Key와 웹훅 서명, TLS, JWE 기반 암호화, Rate Limiting을 조합해 인증·전송·데이터·남용 방지를 여러 계층에서 다룹니다.
소개
20만 개 가맹점이 사용하는 API, 수십 년간 안정적으로 운영하기 위한 토스페이먼츠의 방식
