API 명세서
토스페이 API 소개

토스페이 API 소개

토스를 통한 결제 서비스를 사용하기 위한 API입니다. 토스페이를 활용한 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요! '토스페이 시작하기' 문서로 바로가기

토스페이 개발 가이드는 수시로 업데이트 됩니다. 사전 예고없이 업데이트 될 수 있으니 지속적으로 확인해 주시길 부탁드립니다.

⚠️

토스페이는 결제 과정 중의 보안을 위해 pay.toss.im의 결제 API HTTPS는 TLS v1.2 이상만을 지원합니다. SSL은 필수이며 적용이 되어 있지 않은 서버에서는 이용이 불가합니다.

지원 브라우저

토스페이 서비스를 지원하는 브라우저는 다음과 같습니다.

PC 브라우저, Android, iOS 모두 TLS 1.2 이상의 환경에서 동작이 가능하며, 디바이스 같은 경우 토스 앱의 최소 지원 버전 기준입니다. 토스 앱 최신버전이 아닌 경우, 결제 진행이 원활하지 않을 수 있으니 가급적 최신 버전의 토스앱을 이용해 주시길 부탁드립니다.

  • Safari 12, Chrome 64, Firefox 67, Opera 51, Edge 79 부터 지원
  • Android 6.0 Marshmallow 부터 지원
  • iOS 15 부터 지원
  • Java 를 사용하시는 경우, jdk 1.8 이상 버전 사용을 권장합니다

토스페이는 iframe 방식을 공식적으로 지원하지 않습니다. iframe 방식을 이용하는 경우 결제가 원활하지 않을 수 있으므로 페이지 전환방식의 연동을 권장드립니다.

또한, 토스페이는 기본적으로 Server to Server 호출 방식을 지향합니다. 웹 브라우저를 통하여 클라이언트 단에서 토스 도메인으로 직접 결제 API를 호출하는 방식을 사용할 경우, 결제와 관련된 데이터가 외부에 노출되어 보안사고가 발생할 수 있으니 유의해 주시길 부탁드립니다.

결제 상태

결제 건이 생성된 후, 결제가 진행됨에 따라 결제 상태가 변경되며, 각 결제 상태마다 판매자 또는 구매자가 요청할 수 있는 행동도 변합니다. 아래는 결제 상태 목록과 각 상태에 대한 설명입니다.

결제 상태 코드상태명설명
PAY_STANDBY결제 대기 중결제 건이 생성되었고, 구매자의 결제 진행을 대기 중인 상태. 이 상태에서 구매자나 가맹점이 결제를 취소할 수 있습니다. 또한 설정한 '만료 기간'이 도래하면 자동으로 취소됩니다.
PAY_APPROVED구매자 인증 완료결제를 위한 구매자 인증 완료되고, 가맹점의 최종 승인을 기다리는 상태. ('autoExecute'를 false로 설정한 경우에만 이 단계를 거칩니다. 이 상태에서도 설정한 결제 '유효기간이 만료'되면 자동으로 취소처리 됩니다.)
PAY_CANCEL결제 취소결제가 완료되기 전에 구매자가 결제를 취소하거나 유효기간이 만료된 거래. (금액 이동 없이 종료된 건)
PAY_PROGRESS결제 진행 중구매자가 결제를 승인하여 구매자의 계좌에서 결제 금액을 출금 처리 중인 상태입니다.
PAY_COMPLETE결제 완료구매자 및 가맹점의 결제 승인 및 출금이 정상적으로 완료된 상태입니다.
REFUND_PROGRESS환불 진행 중전액 또는 부분 환불을 진행 중인 상태로, 완료되기 전까지 다른 환불을 진행할 수 없습니다.
REFUND_SUCCESS환불 성공전액 또는 부분 환불이 완료되어, 환불 처리한 금액이 구매자의 계좌로 입금 완료된 상태입니다.
SETTLEMENT_COMPLETE정산 완료결제 완료된 금액에 대해 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과)
SETTLEMENT_REFUND_COMPLETE환불 정산 완료전액 또는 부분 환불에 대한 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과했거나 전액 환불에 대한 정산 완료된 경우)

HTTP 응답 코드

HTTP 응답 코드응답 이름설명
200OK정상
400Bad Request파라미터 오류
401Unauthorized가맹점 API Key 오류
404Not Found존재하지 않는 요청
50xServer Error서버 오류