개발자센터
V1
V2
파트너 정산 릴리즈 노트 기술 블로그

PortOne REST API - V1

결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.

V1 API hostname: api.iamport.kr


인증 관련 API

포트원 API를 호출할 때는 액세스 토큰Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.

액세스 토큰 발급 API를 호출하려면 API 키API 시크릿을 인자로 넣어주어야 합니다.

API 키와 API 시크릿 확인하기

  1. 관리자 콘솔 상점・계정 관리 화면 접속
  2. 내 식별코드・API Keys 버튼 클릭
API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다
API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다

API 시크릿은 절대로 외부에 노출되어서는 안 되는 값입니다.
실제 구현에서 액세스 토큰 발급은 꼭 서버 사이드에서 해주세요.

액세스 토큰 발급 받기

access_token 발급 API post/users/getToken 호출

/users/getToken API를 호출해서 액세스 토큰을 발급받습니다
/users/getToken API를 호출해서 액세스 토큰을 발급받습니다

포트원 REST API 서버는 Google Public NTP의 시간과 동기화되고 있습니다.

하위 상점 연동을 할 경우 액세스 토큰을 발급받을 때 Agent 계정API 키API 시크릿을 사용해야 합니다.

Agency & Tier 란?

액세스 토큰 사용하기

발급받은 액세스 토큰은 다른 API를 호출할 때
Authorization 헤더에 Bearer <액세스 토큰> 형식의 값을 넣어주면 됩니다.

자세한 내용은 MDN - HTTP 인증 문서를 참고해주세요.

하위 상점 연동을 할 경우 포트원 API 호출시 Tier 헤더에 하위 상점 티어 코드를 입력해야 합니다.

Agency & Tier 란?

액세스 토큰 만료기한 연장

만료된 액세스 토큰으로 API를 호출하면 401 Unauthorized 응답을 받습니다.
액세스 토큰의 만료 기한은 발행시간부터 30분입니다.

  • 기존 액세스 토큰이 만료되기 전 access_token 발급 API post/users/getToken를 다시 호출했을 경우

    • 기존 액세스 토큰이 반환됩니다.
      만료 기한이 1분 안쪽으로 남았을 때 요청했다면 기존 액세스 토큰의 만료 기한이 5분 연장됩니다.
  • 기존 액세스 토큰이 만료된 다음 access_token 발급 API post/users/getToken를 다시 호출했을 경우

    • 새로운 액세스 토큰이 반환됩니다.

액세스 토큰의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 상황을 고려해서 설계되었습니다.

  • 한 고객사에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(/users/getToken)를 호출하는 상황
  • 한 고객사에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황

결제 관련 API

결제 금액 사전 등록 관련 API

비인증 결제 관련 API

별도 결제창 호출없이 결제를 진행할 수 있는 비인증 결제 기능을 제공합니다.

정기 결제 관련 API

빌링키 관련 API

가상계좌 관련 API

PG사 관련 API

PG사 별 추가로 지원하는 기능을 제공합니다.

카카오 관련 API

카카오페이에서 지원하는 기능을 제공합니다.

KCP 퀵페이 관련 API

KCP 퀵페이에서 지원하는 기능을 제공합니다.

네이버페이 관련 API

네이버페이에서 지원하는 기능을 제공합니다.

목차

(주문형-네이버페이) 네이버페이 주문환불 API
post/payments/{imp_uid}/naver/cancel
(주문형-네이버페이) 구매자의 환불요청 승인처리 API
post/payments/{imp_uid}/naver/approve-cancel
(주문형-네이버페이) 상품주문 발송처리 API
post/payments/{imp_uid}/naver/ship
(주문형-네이버페이) 교환승인된 상품 재발송처리 API
post/payments/{imp_uid}/naver/ship-exchanged
(주문형-네이버페이) 교환승인된 상품 수거완료처리 API
post/payments/{imp_uid}/naver/collect-exchanged
(주문형-네이버페이) 상품발주처리 API
post/payments/{imp_uid}/naver/place
(주문형-네이버페이) 상품반품요청 API
post/payments/{imp_uid}/naver/request-return
(주문형-네이버페이) 상품 반품승인 처리 API
post/payments/{imp_uid}/naver/approve-return
(주문형-네이버페이) 상품 반품거절 처리 API
post/payments/{imp_uid}/naver/reject-return
(주문형-네이버페이) 상품 반품보류 처리 API
post/payments/{imp_uid}/naver/withhold-return
(주문형-네이버페이) 반품보류상품 반품보류해제 처리 API
post/payments/{imp_uid}/naver/resolve-return
(결제형-네이버페이) 네이버페이 포인트 적립 API
post/payments/{imp_uid}/naver/point
(결제형-네이버페이) 에스크로 주문 확정 API
post/payments/{imp_uid}/naver/confirm
(주문형-네이버페이) 포트원 거래고유번호 기준 네이버페이 상품주문 조회 API
get/payments/{imp_uid}/naver/product-orders
(주문형-네이버페이) 네이버페이 상품주문번호로 상품주문 상세 조회 API
get/naver/product-orders/{product_order_id}
(주문형-네이버페이) 네이버페이 구매평 조회 API
get/naver/reviews
(결제형-네이버페이) 현금영수증 발급 가용액 조회 API
get/payments/{imp_uid}/naver/cash-amount

페이코 관련 API

페이코에서 지원하는 기능을 제공합니다.

페이먼트월 관련 API

페이먼트월에서 지원하는 기능을 제공합니다.

본인인증 관련 API

현금영수증 관련 API

에스크로 관련 API

고객사 정보 관련 API

고객사 정보를 관리하는 기능을 제공합니다.

고객사의 하위 상점 관련 API

하위 상점 관련 API

하위 상점과 관련된 기능을 제공합니다.

기타 API

부가적인 기능을 제공합니다.

베네피아 포인트 관련 API

베네피아 포인트(복지 포인트)와 관련된 기능을 제공합니다.

결제기관 관련 API

get/cards

카드사코드 전체조회 API

카드사정보 리스트를 조회합니다.
카드사표준코드, 카드사명을 모두 조회할 수 있습니다(금융결제원표준코드 기준)
요청 인자 없음

Response

200

code?: integer
응답코드
(Optional)

0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다

message?: string
응답메세지
(Optional)

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

(Optional)
code: string
기관코드

금융결제표준코드

name: string
기관명

금융결제원기재명

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우

404

코드에 해당되는 카드사정보를 찾을 수 없음
try
Request
Key
Value
Request Sample
N/A
get/cards/{card_standard_code}

카드사명 단건조회 API

특정 카드사표준코드를 기준으로 카드명을 조회합니다.
카드사표준코드, 카드사명을 조회할 수 있습니다(금융결제원표준코드 기준)

Request

Path

card_standard_code: string
카드사코드

조회할 카드사 코드

Response

200

code?: integer
응답코드
(Optional)

0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다

message?: string
응답메세지
(Optional)

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

(Optional)
code: string
기관코드

금융결제표준코드

name: string
기관명

금융결제원기재명

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우

404

코드에 해당되는 카드사정보를 찾을 수 없음
try
Request
Request Sample
N/A
get/banks

은행코드 전체조회 API

은행정보 리스트를 조회합니다.
은행표준코드, 은행명을 모두 조회할 수 있습니다(금융결제원표준코드 기준)
요청 인자 없음

Response

200

code?: integer
응답코드
(Optional)

0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다

message?: string
응답메세지
(Optional)

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

(Optional)
code: string
기관코드

금융결제표준코드

name: string
기관명

금융결제원기재명

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우

404

코드에 해당되는 은행정보를 찾을 수 없음
try
Request
Key
Value
Request Sample
N/A
get/banks/{bank_standard_code}

은행명 단건조회 API

은행코드로 은행명을 조회합니다.
은행표준코드, 은행명을 조회할 수 있습니다(금융결제원표준코드 기준)

Request

Path

bank_standard_code: string
은행코드

조회할 은행코드

Response

200

code?: integer
응답코드
(Optional)

0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다

message?: string
응답메세지
(Optional)

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

(Optional)
code: string
기관코드

금융결제표준코드

name: string
기관명

금융결제원기재명

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우

404

코드에 해당되는 은행정보를 찾을 수 없음
try
Request
Request Sample
N/A

편의점 결제 관련 API

편의점 결제를 위한 수납 번호(barcode)와 관련된 기능을 제공합니다.

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다