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
목차
파트너 다건 조회
Request
body를 쿼리 문자열에 포함시켜 보낼 수 있습니다. 자세히 보기
Body
다건 조회 API 에 사용되는 페이지 입력 정보
파트너 필터 입력 정보
Response
200 Ok
반환된 페이지 결과 정보
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
파트너 생성
Request
Body
고객사 서버에 등록된 파트너 지칭 아이디와 동일하게 설정하는 것을 권장합니다. 명시하지 않는 경우 포트원이 임의의 아이디를 발급해드립니다.
파트너 담당자 정보
파트너 계좌 등록을 위한 정보
이미 존재하는 계약 아이디를 등록해야 합니다.
총 256자까지 입력할 수 있습니다.
최대 10개까지 입력할 수 있습니다.
파트너 생성을 위한 유형별 추가 정보
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_FAILED"일 때의 타입
파트너 계좌 인증이 실패한 경우
type이(가)"PLATFORM_CURRENCY_NOT_SUPPORTED"일 때의 타입
지원 되지 않는 통화를 선택한 경우
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_NOT_FOUND"일 때의 타입
파트너 계좌 검증 아이디를 찾을 수 없는 경우
type이(가)"PLATFORM_CONTRACT_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_USER_DEFINED_PROPERTY_NOT_FOUND"일 때의 타입
사용자 정의 속성이 존재 하지 않는 경우
409 Error
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_ALREADY_USED"일 때의 타입
파트너 계좌 검증 아이디를 이미 사용한 경우
type이(가)"PLATFORM_COMPANY_VERIFICATION_ALREADY_USED"일 때의 타입
파트너 사업자 검증 아이디를 이미 사용한 경우
type이(가)"PLATFORM_PARTNER_ID_ALREADY_EXISTS"일 때의 타입
파트너 조회
Request
Path
조회하고 싶은 파트너 아이디
Response
200 Ok
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency 가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
파트너 수정
Request
Path
업데이트할 파트너 아이디
Body
파트너 담당자 업데이트를 위한 정보
파트너 계좌 업데이트를 위한 입력 정보
파트너 유형별 추가 정보를 수정합니다. 기존과 다른 파트너 유형 정보가 입력된 경우, 파트너의 유형 자체가 변경됩니다.
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_FAILED"일 때의 타입
파트너 계좌 인증이 실패한 경우
type이(가)"PLATFORM_INSUFFICIENT_DATA_TO_CHANGE_PARTNER_TYPE"일 때의 타입
파트너 타입 수정에 필요한 데이터가 부족한 경우
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_NOT_FOUND"일 때의 타입
파트너 계좌 검증 아이디를 찾을 수 없는 경우
type이(가)"PLATFORM_CONTRACT_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_USER_DEFINED_PROPERTY_NOT_FOUND"일 때의 타입
사용자 정의 속성이 존재 하지 않는 경우
409 Error
type이(가)"PLATFORM_ACCOUNT_VERIFICATION_ALREADY_USED"일 때의 타입
파트너 계좌 검증 아이디를 이미 사용한 경우
type이(가)"PLATFORM_ARCHIVED_PARTNER"일 때의 타입
보관된 파트너를 업데이트하려고 하는 경우
type이(가)"PLATFORM_COMPANY_VERIFICATION_ALREADY_USED"일 때의 타입
파트너 사업자 검증 아이디를 이미 사용한 경우
type이(가)"PLATFORM_MEMBER_COMPANY_CONNECTED_PARTNER_BRN_UNCHANGEABLE"일 때의 타입
연동 사업자로 연동된 파트너의 사업자등록번호를 변경하려고 시도한 경우
type이(가)"PLATFORM_MEMBER_COMPANY_CONNECTED_PARTNER_TYPE_UNCHANGEABLE"일 때의 타입
연동 사업자로 연동된 파트너의 파트너 유형을 변경하려고 시도한 경우
파트너 다건 생성
Request
Body
Response
200 Ok
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
type이(가)"PLATFORM_CURRENCY_NOT_SUPPORTED"일 때의 타입
지원 되지 않는 통화를 선택한 경우
type이(가)"PLATFORM_PARTNER_IDS_DUPLICATED"일 때의 타입
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_CONTRACTS_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_USER_DEFINED_PROPERTY_NOT_FOUND"일 때의 타입
사용자 정의 속성이 존재 하지 않는 경우
409 Error
type이(가)"PLATFORM_PARTNER_IDS_ALREADY_EXISTS"일 때의 타입
파트너 복원
Request
Path
파트너 아이디
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
409 Error
type이(가)"PLATFORM_CANNOT_ARCHIVE_SCHEDULED_PARTNER"일 때의 타입
예약된 업데이트가 있는 파트너를 보관하려고 하는 경우
파트너 복원
Request
Path
파트너 아이디
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
파트너 연동 사업자 연동
Request
Path
파트너 아이디
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
type이(가)"PLATFORM_MEMBER_COMPANY_NOT_CONNECTABLE_STATUS"일 때의 타입
파트너 연동 사업자 연동 상태가 연동 가능한 상태가 아닌 경우
type이(가)"PLATFORM_PARTNER_TAXATION_TYPE_IS_SIMPLE"일 때의 타입
파트너의 과세 유형이 간이 과세 세금계산서 미발행 유형인 경우
type이(가)"PLATFORM_PARTNER_TYPE_IS_NOT_BUSINESS"일 때의 타입
파트너 유형이 사업자가 아닌 경우
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_BTX_NOT_ENABLED"일 때의 타입
BTX 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
409 Error
type이(가)"PLATFORM_PARTNER_SCHEDULE_EXISTS"일 때의 타입
파트너 수정 예약 건이 존재하는 경우
503 Error
type이(가)"PLATFORM_EXTERNAL_API_FAILED"일 때의 타입
외부 api 오류
연동 사업자 연동 해제
Request
Path
파트너 아이디
Response
200 Ok
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
type이(가)"PLATFORM_MEMBER_COMPANY_NOT_CONNECTED"일 때의 타입
파트너가 연동 사업자로 연동 되어있지 않은 경우
type이(가)"PLATFORM_PARTNER_TAXATION_TYPE_IS_SIMPLE"일 때의 타입
파트너의 과세 유형이 간이 과세 세금계산서 미발행 유형인 경우
type이(가)"PLATFORM_PARTNER_TYPE_IS_NOT_BUSINESS"일 때의 타입
파트너 유형이 사업자가 아닌 경우
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_BTX_NOT_ENABLED"일 때의 타입
BTX 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
409 Error
type이(가)"PLATFORM_ONGOING_TAX_INVOICE_EXISTS"일 때의 타입
진행 중인 세금계산서가 존재하는 경우
503 Error
type이(가)"PLATFORM_EXTERNAL_API_FAILED"일 때의 타입
외부 api 오류
파트너 연동 사업자 일괄 연동
Request
Body
파트너 필터 입력 정보
Response
200 Ok
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_BTX_NOT_ENABLED"일 때의 타입
BTX 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_TARGET_PARTNER_NOT_FOUND"일 때의 타입
처리 대상 파트너가 존재하지 않는 경우
503 Error
type이(가)"PLATFORM_EXTERNAL_API_FAILED"일 때의 타입
외부 api 오류
파트너 연동 사업자 연동 해제
Request
Body
파트너 필터 입력 정보
Response
200 Ok
400 Error
type이(가)"INVALID_REQUEST"일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type이(가)"UNAUTHORIZED"일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type이(가)"FORBIDDEN"일 때의 타입
요청이 거절된 경우
type이(가)"PLATFORM_BTX_NOT_ENABLED"일 때의 타입
BTX 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
type이(가)"PLATFORM_NOT_ENABLED"일 때의 타입
플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404 Error
type이(가)"PLATFORM_PARTNER_NOT_FOUND"일 때의 타입
type이(가)"PLATFORM_TARGET_PARTNER_NOT_FOUND"일 때의 타입
처리 대상 파트너가 존재하지 않는 경우
503 Error
type이(가)"PLATFORM_EXTERNAL_API_FAILED"일 때의 타입
외부 api 오류