PortOne REST API - V2
API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.
V2 API hostname: api.portone.io
요청 및 응답 형식
요청과 응답의 본문은 JSON 형식입니다.
API 응답에 포함된 필드는 별도 안내 없이 추가될 수 있으니, 알지 못하는 필드가 있는 경우에는 무시하도록 개발해 주세요.
API 매개 변수 중 URL 경로에 들어가는 문자열 값이 있는 경우, URL 경로에 들어갈 수 없는 문자열은 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent
함수 등을 사용할 수 있습니다.
인증 방식
V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 콘솔 내 결제연동 탭에서 발급받을 수 있습니다.
인증 관련 API를 제외한 모든 API는 HTTP Authorization
헤더로 인증 정보를 전달해 주셔야 합니다. Authorization 헤더에 전달하는 형식은 두 가지 중 하나입니다.
- API Secret 직접 사용 (간편)
Authorization: PortOne MY_API_SECRET - 액세스 토큰 사용
Authorization: Bearer MY_ACCESS_TOKEN
GET 요청 시 Body 대신 Query 사용
GET 요청 시에 Body를 사용해야 하는 경우, Body 대신 Query를 사용할 수 있습니다.
이 경우, Body 객체를 requestBody
Query 필드에 넣어주시면 됩니다.
인증 관련 API
결제 관련 API
목차
결제 예약 관련 API
빌링키 관련 API
현금 영수증 관련 API
프로모션 관련 API
본인인증 관련 API
파트너 정산 관련 API
정책 관련 API
목차
파트너 관련 API
파트너 다건 조회
Request
body를 쿼리 문자열에 포함시켜 보낼 수 있습니다. 자세히 보기
Body
다건 조회 API 에 사용되는 페이지 입력 정보
파트너 필터 입력 정보
true 이면 보관된 파트너를 조회하고, false 이면 보관되지 않은 파트너를 조회합니다. 기본값은 false 입니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 태그를 하나 이상 가지는 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우, 해당 리스트에 포함되는 계좌 은행을 가진 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우, 해당 리스트에 포함되는 계좌 통화를 가진 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우, 해당 리스트에 포함되는 아이디를 가진 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우, 해당 리스트에 포함되는 기본 계약 id를 가진 파트너만 조회합니다.
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 파트너만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
Response
200
성공 응답으로 조회된 파트너 리스트와 페이지 정보가 반환됩니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
반환된 페이지 결과 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
파트너 생성
Request
Body
고객사 서버에 등록된 파트너 지칭 아이디와 동일하게 설정하는 것을 권장합니다. 명시하지 않는 경우 포트원이 임의의 아이디를 발급해드립니다.
파트너 담당자 정보
이미 존재하는 계약 아이디를 등록해야 합니다.
총 256자까지 입력할 수 있습니다.
최대 10개까지 입력할 수 있습니다.
파트너 생성을 위한 유형별 추가 정보
Response
200
성공 응답으로 생성된 파트너 객체가 반환됩니다.
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우PlatformAccountVerificationFailedError
: 파트너 계좌 인증이 실패한 경우PlatformCurrencyNotSupportedError
: 지원 되지 않는 통화를 선택한 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformContractNotFoundError
PlatformAccountVerificationNotFoundError
: 파트너 계좌 검증 아이디를 찾을 수 없는 경우PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우
409
PlatformPartnerIdAlreadyExistsError
PlatformAccountVerificationAlreadyUsedError
: 파트너 계좌 검증 아이디를 이미 사용한 경우
파트너 조회
Request
Path
조회하고 싶은 파트너 아이디
Response
200
성공 응답으로 파트너 객체가 반환됩니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
은행
통화 단위
플랫폼 계좌 상태
플랫폼 파트너 상태
PENDING
승인 대기 중APPROVED
승인 완료REJECTED
승인 거절파트너 유형별 추가 정보
플랫폼 파트너 과세 유형
플랫폼 파트너 사업자 상태
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError
파트너 수정
Request
Path
업데이트할 파트너 아이디
Body
파트너 담당자 업데이트를 위한 정보
파트너 유형별 추가 정보를 수정합니다. 기존과 다른 파트너 유형 정보가 입력된 경우, 파트너의 유형 자체가 변경됩니다.
Response
200
성공 응답으로 업데이트된 파트너 객체가 반환됩니다.
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우PlatformAccountVerificationFailedError
: 파트너 계좌 인증이 실패한 경우PlatformInsufficientDataToChangePartnerTypeError
: 파트너 타입 수정에 필요한 데이터가 부족한 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError
PlatformContractNotFoundError
PlatformAccountVerificationNotFoundError
: 파트너 계좌 검증 아이디를 찾을 수 없는 경우PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우
409
PlatformArchivedPartnerError
: 보관된 파트너를 업데이트하려고 하는 경우PlatformAccountVerificationAlreadyUsedError
: 파트너 계좌 검증 아이디를 이미 사용한 경우
파트너 다건 생성
Request
Body
고객사 서버에 등록된 파트너 지칭 아이디와 동일하게 설정하는 것을 권장합니다. 명시하지 않는 경우 포트원이 임의의 아이디를 발급해드립니다.
파트너 담당자 정보
파트너 계좌 등록을 위한 정보
이미 존재하는 계약 아이디를 등록해야 합니다.
총 256자까지 입력할 수 있습니다.
최대 10개까지 입력할 수 있습니다.
파트너 생성을 위한 유형별 추가 정보
Response
200
성공 응답
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우PlatformPartnerIdsDuplicatedError
PlatformCurrencyNotSupportedError
: 지원 되지 않는 통화를 선택한 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformContractsNotFoundError
PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우
409
PlatformPartnerIdsAlreadyExistError
파트너 복원
Request
Path
파트너 아이디
Response
200
성공 응답으로 보관된 파트너 객체를 반환합니다.
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError
409
PlatformCannotArchiveScheduledPartnerError
: 예약된 업데이트가 있는 파트너를 보관하려고 하는 경우
파트너 복원
Request
Path
파트너 아이디
Response
200
성공 응답으로 복원된 파트너 객체를 반환합니다.
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError