PortOne REST API - V2
API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.
V2 API hostname: api.portone.io
요청 및 응답 형식
요청과 응답의 본문은 JSON 형식입니다.
API 매개 변수 중 URL 경로에 들어가는 문자열 값이 있는 경우, URL 경로에 들어갈 수 없는 문자열은 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent
함수 등을 사용할 수 있습니다.
인증 방식
V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 관리자콘솔 내 결제연동 탭에서 발급받으실 수 있습니다.
인증 관련 API를 제외한 모든 API는 HTTP Authorization
헤더로 아래 형식의 인증 정보를 전달해주셔야 합니다.
Authorization: PortOne MY_API_SECRET
GET 요청 시 Body 대신 Query 사용하기
GET 요청 시에 Body를 전달해야 하는 경우, Body 대신 Query를 사용할 수 있습니다.
이 경우, Body 객체를 requestBody
Query 필드에 넣어주시면 됩니다.
하위호환성
포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.
-
현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
-
입력 형식 내 필드 정의가 삭제되지 않습니다.
-
필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
- 오로지 선택 입력 정보만 추가될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
enum 타입의 값이 삭제되지 않습니다.
-
-
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
-
출력 형식 내 필드 정의가 삭제되지 않습니다.
-
사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
- 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
- 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
- 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
-
UNSTABLE
이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.
인증 관련 API
결제 관련 API
목차
결제 예약 관련 API
빌링키 관련 API
현금 영수증 관련 API
프로모션 관련 API
본인인증 관련 API
목차
파트너 정산 관련 API
정책 관련 API
목차
파트너 관련 API
목차
정산 상세내역 관련 API
계좌 관련 API
정산 내역 관련 API
지급 내역 관련 API
일괄 지급 내역 관련 API
이체 내역 관련 API
사업자 관련 API
특정 PG사 관련 API
대사 서비스 API
공통 API
타입 정의
oneLine(한 줄 형식 주소) 필드는 항상 존재합니다.
결제가 이미 완료된 경우
결제가 이미 완료되었거나 대기중인 경우
에스크로 배송 정보 등록 성공 응답
추가 수수료 정책 보관 성공 응답
계약 보관 성공 응답
파트너 보관 성공 응답
사업자등록 정보
사업자등록 정보조회 결과
외부 서비스에서 에러가 발생한 경우
B2B 기능이 활성화되지 않은 경우
은행
은행 정보
은행 명칭
배송 정보 등록 전
빌링키가 이미 삭제된 경우
발급 실패 상세 정보
빌링키 다건 조회를 위한 입력 정보
빌링키 정보
빌링키가 존재하지 않는 경우
빌링키 결제 요청 입력 정보
빌링키 발급 수단 정보
카드 정보
간편 결제 정보
충전식 포인트 결제 정보
간편 결제 수단
모바일 정보
페이팔 정보
계좌이체 정보
빌링키 결제 수단
빌링키 결제 완료된 결제 건 요약 정보
빌링키 정렬 기준
빌링키 다건 조회 시 정렬 조건
빌링키 상태
통합검색 입력 정보
통합검색 항목
빌링키 다건 조회 시, 시각 범위를 적용할 필드
결제 취소 금액이 취소 가능 금액을 초과한 경우
현금 영수증 취소 성공 응답
고객 정보 입력 형식
결제 취소 성공 응답
취소 과세 금액이 취소 가능한 과세 금액을 초과한 경우
취소 면세 금액이 취소 가능한 면세 금액을 초과한 경우
취소 가능 잔액 검증에 실패한 경우
발급 취소
결제 취소 상태 건
취소된 현금영수증
거래 취소
결제 취소 상태 건
카드 상세 정보
카드 브랜드
카드 인증 관련 정보
카드 소유주 유형
카드 프로모션
카드 유형
통신사
현금영수증 내역
현금영수증이 이미 발급된 경우
현금영수증 다건 조회를 위한 입력 정보
현금영수증 입력 정보
입력 시 발급 유형
현금영수증이 존재하지 않는 경우
현금영수증이 발급되지 않은 경우
현금영수증 정렬 기준
현금영수증 다건 조회 시 정렬 조건
현금영수증 발급 건 상태
현금영수증 내역
현금영수증 다건 조회 시, 시각 범위를 적용할 필드
발급 유형
채널 그룹 정보
요청된 채널이 존재하지 않는 경우
여러 채널을 지정한 요청에서, 채널 각각에서 오류가 발생한 경우
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
PG사에서 오류를 전달한 경우
가상계좌 말소 성공 응답
에스크로 구매 확정 성공 응답
본인인증 확인 성공 응답
구매 확정
파트너 연동 사업자 일괄 연동 요청 응답
파트너 연동 사업자 연동 요청 응답
국가
결제 예약 성공 응답
플랫폼 생성 성공 응답 정보
계약 객체 생성 성공 응답
할인 정보
외부 결제 상세 정보
orderAmount, orderLines, all 중에서 하나만 입력하여야 합니다.
전체 금액 취소
주문 취소 항목 리스트
추가 수수료 정보
할인 정보
외부 결제 상세 정보
주문 금액 또는 주문 항목 하나만 입력 가능합니다.
주문 항목
상품
파트너 생성을 위한 입력 정보
파트너 계좌 등록을 위한 정보
파트너 담당자 정보
파트너 생성을 위한 유형별 추가 정보
파트너 생성 성공 응답
파트너 다건 생성 성공 응답
통화 단위
고객 정보
고객 정보 입력 정보
두 개의 이름 형식 중 한 가지만 선택하여 입력해주세요.
고객 분리형 이름
시간 범위
요일
빌링키 삭제 성공 응답
빌링키 삭제 완료 상태 건
배송 완료
파트너 연동 사업자 일괄 연동 해제 요청 응답
연동 사업자 연동 해제 요청 응답
프로모션 할인 금액이 결제 시도 금액 이상인 경우
분쟁 내역
분쟁 상태
간편 결제 수단
간편 결제사
실패한 본인인증 내역
결제 실패 상태 건
취소 실패 상태
결제 실패 상태
결제 실패 상태 건
빌링키 발급 실패 채널 응답
요청이 거절된 경우
성별
결제 건 커서 기반 대용량 다건 조회 성공 응답 정보
사업자등록 정보 조회 성공 응답
은행 정보 조회 성공 응답 정보
빌링키 다건 조회 성공 응답 정보
현금영수증 다건 조회 성공 응답 정보
본인인증 내역 다건 조회 성공 응답 정보
카카오페이 주문 조회 응답
결제 예약 다건 조회 성공 응답 정보
결제 시도 내역 조회 응답 정보
결제 건 다건 조회 성공 응답 정보
이체내역 다건 조회 성공 응답 정보
추가 수수료 정책 다건 조회 성공 응답 정보
사업자 조회 성공 응답 정보
계약 다건 조회 성공 응답
정산내역 다건 조회 성공 응답 정보
파트너 다건 조회 성공 응답 정보
본인인증 내역
본인인증 건이 이미 API로 요청된 상태인 경우
본인인증 건이 이미 인증 완료된 상태인 경우
본인인증 실패 정보
본인인증 다건 조회를 위한 고객 정보 입력 정보
본인인증 다건 조회를 위한 입력 정보
본인인증 방식
요청된 본인인증 건이 존재하지 않는 경우
본인인증 건이 API로 요청된 상태가 아닌 경우
본인인증 통신사
요청 시 고객 정보
본인인증 내역 정렬 기준
본인인증 내역 다건 조회 시 정렬 조건
본인인증 상태
본인인증 다건 조회 시, 시각 범위를 적용할 필드
인증된 고객 정보
card
를 반드시 입력해 주세요.
카드 수단 정보 입력 양식
하나의 필드만 입력합니다.
카드 수단 정보 입력 정보
가상계좌 수단 정보 입력 정보
가상계좌 결제 시 현금영수증 정보
validHours와 dueDate 둘 중 하나의 필드만 입력합니다.
가상계좌 발급 방식
pgAccountId, accountNumber 유형 중 한 개의 필드만 입력합니다.
가상계좌 발급 유형
수기 결제가 완료된 결제 건 요약 정보
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
빌링키 발급 성공 응답
현금영수증 발급 시 고객 관련 입력 정보
현금영수증 발급 가능 결제 수단
현금 영수증 발급 성공 응답
발급 실패
빌링키 발급 완료 상태 건
발급 완료
발급 완료된 현금영수증
빌링키 발급 성공 채널 응답
API key 로그인 성공 응답
결제 혹은 본인인증 시도 횟수가 최대에 도달한 경우
동일한 webhook id에 대한 수동 재시도 횟수가 최대에 도달한 경우
에스크로 배송 정보 수정 성공 응답
월 및 일자 정보
프로모션에 의해 조정된 취소 금액이 음수인 경우
한 줄 형식 주소만 존재합니다.
반환된 페이지 결과 정보
다건 조회 API 에 사용되는 페이지 입력 정보
결제 완료 상태 건
결제 완료 상태 건
결제 부분 취소 상태 건
결제 부분 취소 상태 건
수기 결제 성공 응답
결제 완료 대기 상태 건
결제 완료 대기 상태 건
빌링키 결제 성공 응답
결제 건
결제가 이미 취소된 경우
결제 금액 세부 정보
금액 세부 입력 정보
결제 취소 내역
결제 건 내 현금영수증 정보
결제건 내 현금영수증 상태
결제가 발생한 클라이언트 환경
V1 결제 건의 경우 타입이 REGISTERED 로 고정됩니다.
에스크로 수취인 정보
에스크로 발송자 정보
결제 실패 정보
결제 건 다건 조회를 위한 입력 정보
에스크로 상태
할부 정보
배송정보
물류 회사
결제수단 정보
결제수단 카드 정보
편의점 결제 상세 정보
간편 결제 상세 정보
간편 결제 수단
충전식 포인트 결제 정보
상품권 상세 정보
상품권 종류
모바일 상세 정보
계좌 이체 상세 정보
가상계좌 상세 정보
가상계좌 환불 상태
가상계좌 유형
결제 건이 존재하지 않는 경우
결제가 완료되지 않은 경우
결제 건이 입금 대기 상태가 아닌 경우
상품 정보
상품 유형
결제 예약 건
결제 예약건이 이미 존재하는 경우
결제 예약건이 이미 처리된 경우
결제 예약건이 이미 취소된 경우
결제 예약 건 다건 조회를 위한 입력 정보
결제 예약건이 존재하지 않는 경우
결제 예약 건 정렬 기준
결제 예약 건 다건 조회 시 정렬 조건
결제 예약 건 상태
결제 예약 건
결제 건 정렬 기준
결제 건 상태
통합검색 입력 정보
통합검색 항목
어떤 시점을 기준으로 조회를 할 것인지 선택합니다. CREATED_AT: 결제 건 생성 시점을 기준으로 조회합니다. STATUS_CHANGED_AT: 상태 승인 시점을 기준으로 조회합니다. 결제 건의 최종 상태에 따라 검색 기준이 다르게 적용됩니다. ready -> 결제 요청 시점 기준 paid -> 결제 완료 시점 기준 cancelled -> 결제 취소 시점 기준 failed -> 결제 실패 시점 기준 값을 입력하지 않으면 STATUS_CHANGED_AT 으로 자동 적용됩니다.
결제 시도
성공 웹훅 내역
웹훅 발송 시 결제 건 상태
웹훅 요청 정보
웹훅 응답 정보
웹훅 전송 상태
수동 웹훅 재발송, 가상계좌 입금, 비동기 취소 승인 시 발생한 웹훅일 때 필드의 값이 존재합니다.
결제 건 및 커서 정보
결제 완료 대기 상태
채널 별 빌링키 발급 응답
PG사
PG사 결제 모듈
PG사에서 오류를 전달한 경우
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
예금주 조회 성공 응답 정보
플랫폼 계좌 상태
송금 대행을 통해 일어난 정산 금액 지급, 인출 목적의 계좌 이체 결과 정보입니다.
계좌 이체 유형
파트너 계좌 검증 아이디를 이미 사용한 경우
파트너 계좌 인증이 실패한 경우
파트너 계좌 검증 아이디를 찾을 수 없는 경우
추가 수수료 정책는 고객사의 주문건에 대한 중개수수료에 별도로 추가로 부여되는 수수료입니다. 대표적인 사용 예시로 풀필먼트 수수료, 로켓배송 수수료, 마케팅 채널 수수료등이 있습니다.
추가 수수료 정책 다건 조회를 위한 필터 조건
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 추가 수수료 정책만 조회합니다. 하위 필드는 명시된 값 중 한 가지만 적용됩니다.
보관된 추가 수수료 정책을 업데이트하려고 하는 경우
보관된 계약을 업데이트하려고 하는 경우
보관된 파트너를 업데이트하려고 하는 경우
BTX 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
플랫폼 사업자 상태
취소 가능한 금액이 초과한 경우
금액 타입
예약된 업데이트가 있는 추가 수수료 정책을 보관하려고 하는 경우
예약된 업데이트가 있는 계약을 보관하려고 하는 경우
예약된 업데이트가 있는 파트너를 보관하려고 하는 경우
정산 건 식별에 실패한 경우
사업자 정보를 찾을 수 없는 경우
파트너 사업자 검증 아이디를 이미 사용한 경우
파트너 담당자에게 연락하기 위한 정보들 입니다.
계약은 플랫폼 고객사가 파트너에게 정산해줄 대금과 정산일을 계산하는 데 적용되는 정보입니다. 고객사의 플랫폼에서 재화 및 서비스를 판매하기 위한 중개수수료와 판매금에 대한 정산일로 구성되어 있습니다.
계약 다건 조회를 위한 필터 조건
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 계약만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
지원 되지 않는 통화를 선택한 경우
외부 api 오류
외부 api의 일시적인 오류
외부 결제 정보
플랫폼 중개수수료 정보
정률 수수료를 설정하고 싶은 경우 fixedRate
필드에, 정액 수수료를 설정하고 싶은 경우 fixedAmount
필드에 값을 명시해 요청합니다.
두 필드 모두 값이 들어있지 않은 경우 요청이 거절됩니다.
총 금액에 무관하게 정해진 수수료 금액을 책정합니다.
총 금액에 정해진 비율을 곱한 만큼의 수수료를 책정합니다.
파트너 타입 수정에 필요한 데이터가 부족한 경우
수기 정산건
연동 사업자로 연동된 파트너의 사업자등록번호를 변경하려고 시도한 경우
연동 사업자로 연동된 파트너의 파트너 유형을 변경하려고 시도한 경우
파트너 연동 사업자 연동 상태가 연동 가능한 상태가 아닌 경우
파트너가 연동 사업자로 연동 되어있지 않은 경우
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
지원하지 않는 은행인 경우
진행 중인 세금계산서가 존재하는 경우
주문 취소 정산건
정산 금액과 정산 금액 계산에 사용된 금액 정보들 입니다.
주문 정산건
추가 수수료 정보
주문 취소 정보
할인 정보
주문 항목
상품
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
플랫폼 파트너 사업자 상태
파트너 필터 입력 정보
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 파트너만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
플랫폼 파트너 연동 사업자 연결 상태
파트너 수정 예약 건이 존재하는 경우
정산 상태
정산 유형
플랫폼 파트너 상태
플랫폼 파트너 과세 유형
파트너의 과세 유형이 간이 과세 세금계산서 미발행 유형인 경우
파트너 유형별 추가 정보
사업자 유형의 파트너 추가 정보 입니다.
파트너 유형이 사업자가 아닌 경우
플랫폼 파트너 유형 이름
비사업자 유형의 파트너 추가 정보 입니다.
비사업자 유형의 파트너 추가 정보 입니다.
플랫폼에서 발생한 결제 수수료, 부가세 등 금액을 부담하는 주체를 나타냅니다.
결제 정보
결제 수단
카드
간편 결제
간편 결제 입력 정보
상품권
결제 수단 입력 정보
모바일
계좌이체
가상계좌
지급 내역 필터 입력 정보
검색 기준 입력 정보
포트원 결제 정보
금액 타입
정산 가능한 금액을 초과한 경우
정산 취소 요청 금액이 포트원 결제 취소 내역의 취소 금액을 초과한 경우
지체일, 정산일, 기준일로 구성되며, 해당 요소들의 조합으로 실제 정산일을 계산합니다.
플랫폼 정산 기준일
플랫폼 정산 주기 입력 정보
플랫폼 정산 주기 계산 방식
매일 정산
하나의 하위 필드에만 값을 명시하여 요청합니다.
정해진 날짜(월, 일)에 정산
매월 정해진 날(일)에 정산
매주 정해진 요일에 정산
플랫폼 정산 주기 계산 방식
정산 파라미터가 존재하지 않는 경우
플랫폼 정산 파라미터 값
정산 요청 결제 금액이 포트원 결제 내역의 결제 금액을 초과한 경우
정산 요청 공급대가가 포트원 결제 내역의 공급대가를 초과한 경우
정산 요청 면세 금액이 포트원 결제 내역의 면세 금액을 초과한 경우
처리 대상 파트너가 존재하지 않는 경우
플랫폼 과세 유형
정산건은 파트너에 정산해줄 정산 금액과 정산 방식 등이 포함되어 있는 정산 정보입니다. 정산 방식은은 주문 정산, 주문 취소 정산, 수기 정산이 있습니다.
정산 시작일 범위와 정산 일 범위는 둘 중 하나만 입력 가능합니다.
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 정산건만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
다운로드 할 시트 컬럼
정산 상태
파트너 유형
사용자 정의 속성
사용자 정의 속성이 존재 하지 않는 경우
포트원 버전
결제 사전 등록 성공 응답
프로모션
프로모션 적용 가능한 카드사
금액 구간별 프로모션 할인 정책
프로모션 할인 정책
프로모션 혜택 유지 옵션을 이전 부분 취소와 다른 것으로 입력한 경우
프로모션이 존재하지 않는 경우
결제수단이 프로모션에 지정된 것과 일치하지 않는 경우
결제 취소 시 프로모션 예산 미복구
결제 취소 시 프로모션 예산 복구
준비 상태의 본인인증 내역
준비 상태 건
준비 상태 건
추가 수수료 정책 복원 성공 응답
계약 복원 성공 응답
파트너 복원 성공 응답
토큰 재발급 성공 응답
하위 상점 거래 정보
영수증 내 하위 상점 거래 등록 응답
배송 정보 등록 완료
구매 거절 확정
구매 거절
취소 요청 상태
본인인증 요청 재전송 성공 응답
웹훅 재발송 응답 정보
결제 예약 건 취소 성공 응답
결제 예약 취소 상태
결제 예약 완료 상태
(결제, 본인인증 등에) 선택된 채널 정보
채널 타입
본인인증 요청을 위한 고객 정보
본인인증 요청 전송 성공 응답
한 줄 형식 주소와 분리 형식 주소 모두 존재합니다. 한 줄 형식 주소는 분리 형식 주소를 이어 붙인 형태로 생성됩니다.
분리 형식 주소 입력 정보
정렬 방식
결제 시작 상태
취소 완료 상태
결제 성공 상태
면세 금액 등 하위 항목들의 합이 전체 취소 금액을 초과한 경우
면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
추가 수수료 정책 업데이트 성공 응답
계약 객체 업데이트 성공 응답
파트너 계좌 업데이트를 위한 입력 정보
파트너 담당자 업데이트를 위한 정보
파트너 유형별 추가 정보를 수정합니다. 기존과 다른 파트너 유형 정보가 입력된 경우, 파트너의 유형 자체가 변경됩니다.
파트너 업데이트 성공 응답
완료된 본인인증 내역
가상계좌 발급 완료 상태 건
가상계좌 발급 완료 상태 건
웹훅 내역이 존재하지 않는 경우