PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
자세한 사항은TLS 지원 범위를 참고해주세요.
V1 API hostname: api.iamport.kr
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization
헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
결제 관련 API
목차
결제 상세내역 조회 API
Request
Path
Response
200
정상 조회
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
유효하지 않은 imp_uid
405
허용되지 않는 HTTP METHOD
결제내역 단건조회 API
Request
Path
Response
200
정상 조회
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
유효하지 않은 imp_uid
결제내역 복수조회 API
(예시) /payments?imp_uid[]=imp_448280090638&imp_uid[]=imp_448280090639&merchant_uid[]=merchant_143434085216
Request
Query
Response
200
요청된 모든 imp_uid 에 대한 결제정보 응답완료
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
207
요청된 imp_uid 중 일부 거래 조회 실패(ex. 접근권한없음 또는 존재하지 않는 imp_uid)
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
해당되는 결제건을 찾지 못하였습니다.
결제 단건조회(고유 고객사 주문번호 조회) API
동일한 merchant_uid가 여러 건 존재하는 경우, 정렬 기준에 따라 가장 첫 번째 해당되는 건을 반환합니다. (모든 내역에 대한 조회가 필요하시면 GET 결제 복수조회(고객사 주문번호 중복 포함) API를 사용해주세요.)
payment_status를 추가로 지정하시면, 해당 status에 해당하는 가장 최신 데이터를 반환합니다.
Request
Path
Query
Response
200
정상 조회
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
거래건이 존재하지 않는 경우
결제 복수조회(고객사 주문번호 중복 포함) API
동일한 merchant_uid가 여러 건 존재하는 경우, 존재하는 모든 거래가 조회됩니다.
payment_status를 추가로 지정하시면, 해당 status에 해당하는 가장 최신 데이터를 반환합니다.
Request
Path
Query
Response
200
정상 조회
400
merchant_uid누락, 올바르지 않은 status 등 파라메터가 잘못된 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
유효하지 않은 merchant_uid
결제상태기준 복수조회 API
검색기간은 최대 90일까지이며 to파라메터의 기본값은 현재 unix timestamp이고 from파라메터의 기본값은 to파라메터 기준으로 90일 전입니다. 때문에, from/to 파라메터가 없이 호출되면 현재 시점 기준으로 최근 90일 구간에 대한 데이터를 검색하게 됩니다.
from, to 파라메터를 지정하여 90일 단위로 과거 데이터 조회는 가능합니다.
Request
Path
Query
Response
200
정상 조회
400
유효하지 않은 payment_status인 경우, 데이터 범위를 넘어선 page인 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
결제취소 API
신용카드/실시간계좌이체/휴대폰소액결제의 경우 즉시 취소처리가 이뤄지게 되며, 가상계좌와 휴대폰소액결제 익월 환불(KCP)의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다. (가상계좌 환불, 휴대폰소액결제 익월 환불(KCP)의 경우 관련 특약계약 필요)
Request
Body
(부분)취소요청금액으로 누락하거나 0을 입력 시 전액취소를 요청합니다.
(부분)취소요청금액 중 면세금액으로 누락되면 0원처리합니다.
(부분)취소요청금액 중 부가세 금액으로 기본값은 null
입니다.
취소 트랜잭션 수행 전, 현재시점의 취소 가능한 잔액
환불받을 계좌의 은행코드
Response
200
정상 조회
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우