PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
V1 API hostname: api.iamport.kr
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
API 키와 API 시크릿 확인하기
API 키와 API 시크릿 확인하기
- 관리자 콘솔
상점・계정 관리화면 접속 내 식별코드・API Keys버튼 클릭
API 시크릿은 절대로 외부에 노출되어서는 안 되는 값입니다.
실제 구현에서 액세스 토큰 발급은 꼭 서버 사이드에서 해주세요.
액세스 토큰 발급 받기
액세스 토큰 발급 받기
포트원 REST API 서버는 Google Public NTP의 시간과 동기화되고 있습니다.
하위 상점 연동을 할 경우 액세스 토큰을 발급받을 때 Agent 계정의 API 키 와 API 시크릿을 사용해야 합니다.
액세스 토큰 사용하기
액세스 토큰 사용하기
발급받은 액세스 토큰은 다른 API를 호출할 때
Authorization 헤더에 Bearer <액세스 토큰> 형식의 값을 넣어주면 됩니다.
자세한 내용은 MDN - HTTP 인증 문서를 참고해주세요.
액세스 토큰 만료기한 연장
액세스 토큰 만료기한 연장
만료된 액세스 토큰으로 API를 호출하면 401 Unauthorized 응답을 받습니다.
액세스 토큰의 만료 기한은 발행시간부터 30분입니다.
-
기존 액세스 토큰이 만료되기 전
access_token 발급 API post/users/getToken 를 다시 호출했을 경우- 기존 액세스 토큰이 반환됩니다.
만료 기한이 1분 안쪽으로 남았을 때 요청했다면 기존 액세스 토큰의 만료 기한이 5분 연장됩니다.
- 기존 액세스 토큰이 반환됩니다.
-
기존 액세스 토큰이 만료된 다음
access_token 발급 API post/users/getToken 를 다시 호출했을 경우- 새로운 액세스 토큰이 반환됩니다.
액세스 토큰의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 상황을 고려해서 설계되었습니다.
- 한 고객사에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(
/users/getToken)를 호출하는 상황 - 한 고객사에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황
결제 관련 API
목차
결제 금액 사전 등록 관련 API
결제금액 단건 수정 API
Request
Body
이미 사전등록한 가맹점 주문번호
수정 할 결제건의 결제예정금액
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
사전 등록한 가맹점의 주문번호
사전 등록한 결제 예정 금액
401
404
결제금액 사전등록 API
이 API를 통해 사전등록된 가맹점 주문번호(merchant_uid)에 대해, IMP.request_pay()에 전달된 merchant_uid가 일치하는 주문의 결제금액이 다른 경우 PG사 결제창 호출이 중단됩니다.
Request
Body
결제금액을 사전 등록할 결제건의 가맹점 주문번호
사전 등록할 결제예정금액
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
사전 등록한 가맹점의 주문번호
사전 등록한 결제 예정 금액
401
결제금액 단건조회 API
Request
Path
결제금액을 조회할 결제건의 가맹점 주문번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
사전 등록한 가맹점의 주문번호
사전 등록한 결제 예정 금액