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 호출시 Tier
헤더에 하위 상점 티어 코드를 입력해야 합니다.
액세스 토큰 만료기한 연장
액세스 토큰 만료기한 연장
만료된 액세스 토큰으로 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
정기 결제 관련 API
목차
빌링키 관련 API
목차
가상계좌 관련 API
PG사 관련 API
카카오 관련 API
KCP 퀵페이 관련 API
페이코 관련 API
페이먼트월 관련 API
본인인증 관련 API
현금영수증 관련 API
발급내역 단건 조회 API
Request
Path
현금영수증을 조회할 결제건의 포트원 거래고유번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
결제건의 포트원 거래고유번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp
401
404
현금영수증 단건발급 API
imp_uid 거래를 처리하는데 사용된 PG설정값을 그대로 활용합니다.
(ex. KCP 거래건이면 KCP를 통해 현금영수증 발행 API처리)
현금영수증 발급 금액은 현금성 거래의 금액으로 자동 적용됩니다. 부분취소된 거래인 경우 남은 잔액으로 발급됩니다.
지원되는 PG사
- KG 이니시스
- NHN KCP
- 나이스페이먼츠
- KICC
- 헥토파이낸셜(구 세틀뱅크)
- 키움페이(구 다우, 페이조아)
- 토스페이먼츠 - 신모듈
- KSNET
- 스마트로 - 신모듈
- (신) 나이스페이
- 웰컴페이먼츠
Request
Path
현금영수증을 발급할 결제건의 포트원 거래 고유번호
Body
현금영수증 발행 주문 상품구분
현금영수증 발행대상 식별정보로 국세청현금영수증카드
, 휴대폰번호
, 주민등록번호
, 사업자등록번호
를 기재합니다.
현금영수증를 발행대상의 식별정보 구분코드
현금영수증 발행할 대상의 타입
현금영수증 발행 상점 고객센터 번호
현금영수증 발행 상점 사업자 명
현금영수증 발행 상점 사업자 번호
현금영수증 발행건 사후 추적을 위해 입력을 강력히 권장합니다.
현금영수증을 발행할 결제건의 구매자 Email 주소
현금영수증 발행건 사후 추적을 위해 입력을 강력히 권장합니다.
발행금액의 1/11 이 부가세로 자동 적용되므로, 부가세금액 조정을 위해서는 tax_free
파라메터를 활용해주세요.
부가세(지정하지 않으면 공급가액의 10%로 자동 적용)
부가세 지정 가맹점에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다.
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
결제건의 포트원 거래고유번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp
400
401
500
501
포트원 발급분 취소 API
포트원과 별개로 거래된 현금영수증 취소는 DELETE 외부 발급분 취소 API를 이용해주세요.
지원되는 PG사
- KG 이니시스
- NHN KCP
- 헥토파이낸셜(구 세틀뱅크)
- 나이스페이먼츠
- 키움페이(구 다우, 페이조아)
- 토스페이먼츠 - 신모듈
- (신) 나이스페이
- KSNET
- 스마트로 - 신모듈
- 웰컴페이먼츠
Request
Path
현금영수증을 취소할 결제건의 포트원 거래고유번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
결제건의 포트원 거래고유번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp
400
401
500
501
외부 발급내역 단건 조회 API
Request
Path
현금영수증 발행 대상 가맹점 주문번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
현금영수증을 발행한 가맹점의 주문번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp
401
404
현금영수증 발급(외부) API
지원되는 PG사
- KG이니시스
- NHN KCP
- 나이스페이먼츠
- KICC
- 헥토파이낸셜(구 세틀뱅크)
- 토스페이먼츠 - 신모듈
- KSNET
- 스마트로 - 신모듈
- (신) 나이스페이
- 웰컴페이먼츠
Request
Path
가맹점 주문번호는 현금거래 주문번호와 동일한 번호를 기재해야 추후 대사가 가능한점 유념하시기 바랍니다.
Body
현금영수증 발행할 결제건의 주문명
현금영수증 발행할 결제건의 금액
현금영수증 발행할 결제건의 주문 상품구분
현금영수증 발행대상 식별정보로 국세청현금영수증카드
, 휴대폰번호
, 주민등록번호
, 사업자등록번호
를 기재합니다.
현금영수증 발행대상의 식별정보 구분코드
현금영수증 발행할 대상의 타입
현금영수증 발행건 사후 추적을 위해 입력을 강력히 권장합니다.
현금영수증을 발행할 결제건의 구매자 Email 주소
현금영수증 발행건 사후 추적을 위해 입력을 강력히 권장합니다.
발행금액의 1/11 이 부가세로 자동 적용되므로, 부가세금액 조정을 위해서는 tax_free 파라메터를 활용해주세요.
현금영수증을 발행할 PG사 구분코드
부가세 지정 가맹점에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다.
현금영수증 발행 상점 사업자 번호
현금영수증 발행 할 결제건의 결제수단
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
현금영수증을 발행한 가맹점의 주문번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp
400
401
500
501
외부 발급분 취소 API
지원되는 PG사
- KG이니시스
- NHN KCP
- 헥토파이낸셜(구 세틀뱅크)
- 나이스페이먼츠
- 토스페이먼츠 - 신모듈
- KSNET
- 스마트로 - 신모듈
- (신) 나이스페이
- 웰컴페이먼츠
Request
Path
merchant_uid는 현금결제를 구분할 고유주문번호를 의미하며 발행에 사용된 값을 전달하면 됩니다.
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
현금영수증을 발행한 가맹점의 주문번호
결제건에 대해 현금영수증 발행시 PG사의 발행고유번호
결제건에 대해 현금영수증 발행시 국세청 발행번호
현금영수증 발행 대상의 타입
현금영수증 발행 금액
현금영수증 발행금액 중 부가세액
발행된 현금영수증을 확인할 수 있는 URL
현금영수증 발행시각 UNIX timestamp
현금영수증 발행취소시각 UNIX timestamp