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
빌링키 다건 조회
Request
body를 쿼리 문자열에 포함시켜 보낼 수 있습니다. 자세히 보기
Body
다건 조회 API 에 사용되는 페이지 입력 정보
빌링키 다건 조회 시 정렬 조건
빌링키 다건 조회를 위한 입력 정보
Response
200 Ok
반환된 페이지 결과 정보
400 Error
type
이(가)"INVALID_REQUEST"
일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type
이(가)"UNAUTHORIZED"
일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type
이(가)"FORBIDDEN"
일 때의 타입
요청이 거절된 경우
빌링키 발급
Request
Body
접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.
card
를 반드시 입력해 주세요.
채널 키 또는 채널 그룹 ID 필수
채널 키 또는 채널 그룹 ID 필수
고객 정보 입력 정보
빌링키 발급 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다. 입력된 값이 없을 경우에는 빈 배열로 해석됩니다.
Response
200 Ok
400 Error
type
이(가)"INVALID_REQUEST"
일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type
이(가)"UNAUTHORIZED"
일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type
이(가)"FORBIDDEN"
일 때의 타입
요청이 거절된 경우
404 Error
type
이(가)"CHANNEL_NOT_FOUND"
일 때의 타입
요청된 채널이 존재하지 않는 경우
502 Error
type
이(가)"CHANNEL_SPECIFIC"
일 때의 타입
여러 채널을 지정한 요청에서, 채널 각각에서 오류가 발생한 경우
type
이(가)"PG_PROVIDER"
일 때의 타입
PG사에서 오류를 전달한 경우
빌링키 단건 조회
Request
Path
조회할 빌링키
Query
접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.
Response
200 Ok
status
이(가)"DELETED"
일 때의 타입
빌링키 삭제 완료 상태 건
status
이(가)"ISSUED"
일 때의 타입
빌링키 발급 완료 상태 건
400 Error
type
이(가)"INVALID_REQUEST"
일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type
이(가)"UNAUTHORIZED"
일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type
이(가)"FORBIDDEN"
일 때의 타입
요청이 거절된 경우
404 Error
type
이(가)"BILLING_KEY_NOT_FOUND"
일 때의 타입
빌링키가 존재하지 않는 경우
빌링키 삭제
Request
Path
삭제할 빌링키
Query
접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.
네이버페이: 자동결제 해지 사유입니다. 명시가 필요합니다.
Response
200 Ok
400 Error
type
이(가)"INVALID_REQUEST"
일 때의 타입
허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401 Error
type
이(가)"UNAUTHORIZED"
일 때의 타입
인증 정보가 올바르지 않은 경우
403 Error
type
이(가)"FORBIDDEN"
일 때의 타입
요청이 거절된 경우
404 Error
type
이(가)"BILLING_KEY_NOT_FOUND"
일 때의 타입
빌링키가 존재하지 않는 경우
type
이(가)"BILLING_KEY_NOT_ISSUED"
일 때의 타입
409 Error
type
이(가)"BILLING_KEY_ALREADY_DELETED"
일 때의 타입
빌링키가 이미 삭제된 경우
type
이(가)"PAYMENT_SCHEDULE_ALREADY_EXISTS"
일 때의 타입
결제 예약건이 이미 존재하는 경우
502 Error
type
이(가)"CHANNEL_SPECIFIC"
일 때의 타입
여러 채널을 지정한 요청에서, 채널 각각에서 오류가 발생한 경우
type
이(가)"PG_PROVIDER"
일 때의 타입
PG사에서 오류를 전달한 경우