API 버전 정책

토스페이먼츠 API 버전에 따라 API에 전송할 수 있는 파라미터의 종류, 응답 필드 등이 변경될 수 있습니다.

새로운 버전을 릴리즈 하더라도 상점에서 사용하고 있는 API의 버전은 변경하지 않습니다. 상점에서 운영 중인 코드의 하위 호환을 지원합니다.

릴리즈 노트를 참고해서 새로운 버전의 변경 사항을 파악하고 개발을 마친 뒤 상점의 개발자센터에서 버전을 변경하세요.

토스페이먼츠 API는 2022년 6월 8일 부터 API 릴리즈 날짜를 YYYY-MM-DD로 표기하는 날짜 기반 버전 관리(Calender Versioning)를 사용합니다.

버전 1.4 까지는 유의적 버전 관리(Semantic Versioning) 방식으로 표기하되 Major.Minor 까지만 사용합니다.

API에 생기는 변경 사항 중 이전 버전과 호환되지 않는 변경 사항을 배포하면 새로운 버전을 릴리즈합니다. 이전 버전과 호환되는 변경 사항을 배포할 때는 버전을 새로 릴리즈하지 않습니다. 자세한 기준은 아래 내용을 참고해주세요.

토스페이먼츠에서는 다음과 같은 변경 사항의 하위 호환을 지원합니다. 따라서 새로운 버전 릴리즈 없이 기존 API에 반영합니다. 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영되니 유의하세요. 자세한 내용은 요청·응답 본문을 참고하세요.

• 새로운 API 엔드포인트 추가
• API 요청에 새로운 선택 파라미터 추가
• API 요청에서 사용하는 필수 파라미터를 선택 파라미터로 변경
• API 응답에 새로운 필드 추가
• 새로운 ENUM 추가
• 에러 메시지 변경
• 새로운 에러 코드 추가
• 새로운 웹훅 이벤트 추가
• 웹훅 이벤트 본문에 새로운 필드 추가

토스페이먼츠에서는 다음과 같은 변경 사항이 배포될 때 새로운 버전을 릴리즈합니다.

• API 엔드포인트 제거
• API 요청에 새로운 필수 파라미터 추가
• API 요청의 선택 파라미터를 필수 파라미터로 변경
• API 응답에 사용되던 필드 삭제
• API 응답 필드 중 nullable 하지 않았던 필드를 nullable 하게 변경
• API 응답 필드의 데이터 타입 변경
• 같은 의미를 나타내는 에러 코드의 변경
• 같은 의미를 나타내는 ENUM 코드의 변경 (예: 토스결제 → 토스페이)

API 버전은 개발자센터에서 확인·변경할 수 있습니다.

가입 후 자동으로 생성되는 테스트 상점의 API 버전은 최신 버전입니다.

계약 후 상점아이디(MID)가 발급된 내 상점의 API 버전은 다를 수 있습니다. 내 상점의 테스트 환경 API 버전과 라이브 환경에서도 API 버전을 다르게 사용할 수 있습니다. 내 상점의 테스트 환경 API 버전은 계약 신청이 완료되었을 때, 라이브 API 버전은 계약 완료 시점에 API 키 발급과 함께 정해집니다.