PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
2024년 9월 1일부로 포트원 V1 API에 대해 일부 보안 규격이 지원 종료됩니다.
자세한 사항은 TLS 지원 범위를 참고해주세요.
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
목차
결제예약 복수조회 API
Request
Query
Response
200 Ok
400 Error
검색 파라메터가 유효하지 않은 경우
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
결제 예약 API
비 인증 결제(빌링키) API를 포트원이 대신 수행하는 개념)
결제 요청에 대한 결과는 notice_url에 설정한 EndPoint URL로 웹훅을 통해 수신(POST request)받을 수 있습니다.
- 기존에 빌링키가 등록된 customer_uid가 존재하는 경우 해당 customer_uid와 해당되는 빌링키로 schedule정보가 예약됩니다.(카드정보 선택사항)
- 등록된 customer_uid가 없는 경우 빌링키 신규 발급을 먼저 진행한 후 schedule정보를 예약합니다.(카드정보 필수사항)
- 예약건 별로 고유의 merchant_uid를 전달해주셔야 합니다.
- schedules의 상세정보(선택정보) buyer_name, buyer_email, buyer_tel, buyer_addr, buyer_postcode 누락시,
customer_uid에 해당되는 customer_name, customer_email, customer_tel, customer_addr, customer_postcode 정보로 대체됩니다.(둘 다 입력시 buyer_* 정보를 우선합니다) - 슈퍼빌링키의 customer_uid로 요청하는 경우, 결제 시점 해당 스마트 라우팅 그룹 내 채널 비율 설정에 따라 결제를 요청합니다. 특정 빌링키로 결제를 요청하려면 channelKey에 결제를 희망하는 빌링키의 채널 키를 입력해 주세요.
Request
Body
Response
200 Ok
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
결제 예약취소 API
Request
Body
Response
200 Ok
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
결제예약 단건조회 API
Request
Path
Response
200 Ok
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404 Error
merchant_uid로 조회되는 예약결제건이 존재하지 않는 경우
결제요청 예약시각 수정 API
Request
Path
Body
Response
200 Ok
400 Error
필수 파라미터 누락, 이미 실행 혹은 취소된 결제예약, 예약시각이 현재 시각보다 과거인 경우
404 Error
존재하지 않는 결제예약
500 Error
포트원 내부 이슈로 인한 API 호출 실패
결제 실패 재예약 API
Request
Path
Body
Response
200 Ok
400 Error
필수 파라미터 누락, 아직 실행되지 않거나 이미 실행 중 혹은 승인된 결제예약, 예약시각이 현재 시각보다 과거인 경우
404 Error
존재하지 않는 결제예약
500 Error
포트원 내부 이슈로 인한 API 호출 실패
결제 실패 재시도 API
Request
Path
Response
200 Ok
400 Error
필수 파라미터 누락, 아직 실행되지 않거나 이미 실행중 혹은 승인된 결제예약
404 Error
존재하지 않는 결제예약 혹은 빌링키
500 Error
미지원 PG사, 포트원 내부 이슈 등으로 인한 API 호출 실패
결제예약 복수조회(빌링키) API
customer_uid별 결제예약목록을 조회할 수 있습니다. 결제예약정보가 (페이징된)목록으로 전달되며, 최대 3개월 단위로 조회가 가능합니다.
결제예약정보가 예약된 시각 기준으로 최신순으로 정렬되어 전달됩니다.
Request
Path
Query
Response
200 Ok
400 Error
검색 파라메터가 유효하지 않은 경우
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우