PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
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 시크릿을 인자로 넣어주어야 합니다.
결제 관련 API
목차
결제 금액 사전 등록 관련 API
비인증 결제 관련 API
비 인증 결제(일회성) API
빌링키 저장 시, buyer_email, buyer_name 등의 정보는 customer 부가정보인 customer_email, customer_name 등으로 함께 저장됩니다.
빌링키 발급 API참조
Request
Body
고객사 거래 고유번호로 매 결제요청 시 고유값으로 요청해야 합니다.
통화 e.g.) KRW, USD, VND, ... Default: KRW
결제요청 할 금액
amount 중 면세공급가액
부가세를 지정할 수 있으며, tax_free=0, vat_amount=0으로 영세율로 결제 가능합니다.
PG사와의 사전 협의 후 사용가능합니다. (기본값: null)
Deprecated 되었습니다. tax_free 파라메터를 사용해주세요.결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)
카드번호(dddd-dddd-dddd-dddd) 기재 양식을 유의하세요.
카드 유효기간(YYYY-MM) 기재 양식을 유의하세요.
PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.
생년월일 기재가 필요없는 해외 PG사 결제 요청의 경우 000000으로 고정 기재하도 무방합니다.
PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.
결제 요청할 카드의 인증번호 (카드 뒷면 3자리, AMEX의 경우 4자리)
빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제 요청할 PG사 구분코드
스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사로 결제 요청을 합니다.
결제요청 할 결제건의 주문명
결제건의 구매자명
결제건의 주문자 E-mail주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제금액 50,000원 이상 한정으로 2 이상의 integer 할부개월수가 적용가능합니다.
카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (PG사와 사전 계약이 필요)
승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. PG사 영업담당자와 계약 당시 사전 협의 필요
거래정보와 함께 저장할 추가 정보
결제성공 시 통지될 Notification URL(Webhook URL)
구매자 브라우저(PC)의 IP
해외PG 전용 파라미터로 3D secure 인증 후 결제시 PG사에서 부여한 결제 ID
해외PG 전용 파라미터로 3D secure 인증 후 결제시 PG사에서 부여한 토큰
결제 요청할 판매 상품에 대한 구분 값
promotion-id-로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다.
Response
200 Ok
정상 결제
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
비 인증 결제(빌링키) API
Request
Body
빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제 요청할 결제건의 고객사 거래 고유번호
통화 e.g.) KRW, USD, VND, ... Default: KRW
결제 요청할 금액
amount 중 면세공급가액
부가세를 지정할 수 있으며, tax_free=0, vat_amount=0으로 영세율로 결제 가능합니다.(기본값: null)
Deprecated 되었습니다. tax_free 파라메터를 사용해주세요.결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)
결제 요청할 결제건의 제품명
결제건의 주문자명
결제건의 주문자 E-mail주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제건의 카드 할부 개월 수로 기본값은 **0(일시불)**입니다.
카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (PG사와 사전 계약이 필요)
승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. PG사 영업담당자와 계약 당시 사전 협의 필요
거래정보와 함께 저장할 추가 정보
결제성공 시 통지될 Notification URL(Webhook URL)
구매자 브라우저(PC)의 IP (입력하지 않은 경우 API를 호출한 클라이언트 IP로 설정됩니다.)
결제 요청할 판매 상품에 대한 구분 값
결제 상품의 개수로 기본값은 1입니다.
현금영수증 발행대상의 구분 값
전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요
비인증 결제 요청 시 추가 파라미터
promotion-id-로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다.
다수 채널에 대해 발급된 빌링키에 대해, 결제 채널을 특정하고 싶을 때 명시
Response
200 Ok
정상 결제
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우