PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
이 문서는 V1 전용입니다. 최신 V2 버전 사용을 권장합니다.
2026년 1월 26일부로 포트원 V1 결제내역 단건조회 API에 동작 변경이 있습니다.
자세한 사항은 V1 결제내역 단건조회 API 동작 변경 안내를 참고해주세요.
V1 API hostname: api.iamport.kr
하위호환성
포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.
-
현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
-
입력 형식 내 필드 정의가 삭제되지 않습니다.
-
필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
- 오로지 선택 입력 정보만 추가될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
enum 타입의 값이 삭제되지 않습니다.
-
-
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
-
출력 형식 내 필드 정의가 삭제되지 않습니다.
-
사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
- 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
- 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
- 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
- 새로운 필드 및 값이 추가되는 경우 사전 공지를 통해 안내드립니다.
-
UNSTABLE이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.
하위 상점의 API 사용
하위 상점에 대해 API를 사용하려는 경우 API 호출 시 Tier 헤더(HTTP Request Header)로 하위상점의 티어코드를 전달해야 합니다.
[Agency & Tier 란?]
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
access_token 발급 API
access_token의 만료기한은 발행 시간 부터 30분입니다. 만료된 토큰으로 API 요청을 하면 401 Unauthorized 응답을 받습니다.
- 재발행 (만료 후 발급): 새로운 access token을 발급한다. (만료기한: 발행시간 후 30분)
- 재사용 (만료 전 발급): 기존 access token을 발급한다. (만료기한: 기존과 동일, 단 기존 만료시간 전 1분이내 요청 시 5분 연장 됨)
Request
Body
REST API key로 포트원 관리자콘솔 내 [결제 연동] > [식별코드・API Keys] > [V1 API]에서 확인할 수 있습니다. : https://admin.portone.io
REST API Secret으로 포트원 관리자콘솔 내 [결제 연동] > [식별코드・API Keys] > [V1 API]에서 확인할 수 있습니다. : https://admin.portone.io
Response
200 Ok
정상적으로 access_token을 받아왔습니다
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
401 Error
imp_key, imp_secret 인증에 실패한 경우