개발자센터
V1
V2
API & SDK
릴리즈 노트 기술 블로그

PortOne REST API - V1

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

V1 API hostname: api.iamport.kr

Swagger JSON 내려받기Postman 등에서 import하여 활용할 수 있습니다.

인증 관련 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

에스크로 결제 건의 배송 정보와 관련된 기능을 제공합니다.
get/escrows/logis/{imp_uid}

배송정보 단건조회 API

에스크로 결제 건에 대한 배송정보 조회
입력한 배송정보를 획득합니다.

택배사 코드표 : https://developers.portone.io/docs/ko/tip/code

지원되는 PG사

  • KG이니시스
  • NHN KCP
  • 키움페이(구 다우, 페이조아)(다우테이타)
  • KSNET
  • 스마트로 - 신모듈(PG사와의 사전 계약이 반드시 필요합니다.)
  • (신) 나이스페이
  • 웰컴페이먼츠

Request

Path

imp_uid: string
포트원 거래고유번호

배송정보를 조회하고자 하는 에스크로 결제건의 포트원 거래고유번호

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
company: string
택배사코드

에스크로 결제건의 택배사 코드

invoice: string
송장번호

에스크로 결제건의 송장번호

sent_at: integer
발송 시각

에스크로 결제건의 배송 발송 시각 UNIX timestamp

applied_at: integer
등록 시각

에스크로 결제건의 배송 정보 등록 시각 UNIX timestamp

400

필수 파라메터가 누락되거나 (PG사별로 필수 여부가 다를 수 있음), 지원하는 않는 PG사인 경우

401

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

404

배송정보를 조회할 거래건이 존재하지 않음

409

등록된 배송정보가 존재하지 않습니다.

500

배송정보 조회 도중 오류 발생
try
Request
Response Status: N/A
N/A
put/escrows/logis/{imp_uid}

배송정보 단건수정 API

에스크로 결제 건에 대해서 PUT /escrows/logis/{imp_uid} 로 등록된 배송정보를 수정하는 API 입니다.(2-depth의 json으로 Request Body가 구성되어야 합니다)

logis는 하위 필드가 모두 필수입니다.
sender, receiver의 각 세부 항목은 PG사마다 필수 여부가 모두 다릅니다.

지원되는 PG사

  • KG이니시스
  • 키움페이(구 다우, 페이조아)(다우테이타)
  • KSNET
  • 스마트로 - 신모듈 (PG사와의 사전 계약이 반드시 필요합니다.)
  • 웰컴페이먼츠

Request

Path

imp_uid: string
포트원 거래고유번호

배송정보를 수정하고자 하는 에스크로 결제건의 포트원 거래고유번호

Body

sender: EscrowLogisSenderAnnotation
발신자 정보

배송을 보내는 발신자의 정보(이름, 연락처, 주소, 우편번호, 수신자와의 관계)

receiver: EscrowLogisReceiverAnnotation
수신자 정보

배송을 받는 수신자의 정보(이름, 연락처, 주소, 우편번호)

logis: EscrowLogisInfoAnnotation
배송정보

택배사코드표는 메뉴얼 참조

products?: EscrowLogisProductsAnnotation[]
배송 상품 정보
(Optional)

배송 보내는 상품의 정보 (고유 아이디, 이름, 고유 코드, 통화코드, 수량, 카테고리)

id: string
상품 고유 아이디
name: string
상품 이름
code?: string
상품 코드
(Optional)

가맹점에서 사용하는 상품 관리 코드

amount: number
상품 단위 가격
currency?: string
상품의 결제통화 구분코드
(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

quantity?: integer
상품의 수량
(Optional)

상품의 수량으로 기본값은 1입니다.

tag?: string
상품의 카테고리
(Optional)

상품의 카테고리 e.g) 도서, 가전기기, 인테리어 용품 등

Response

200

수정 완료
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
company: string
택배사코드

에스크로 결제건의 택배사 코드

invoice: string
송장번호

에스크로 결제건의 송장번호

sent_at: integer
발송 시각

에스크로 결제건의 배송 발송 시각 UNIX timestamp

applied_at: integer
등록 시각

에스크로 결제건의 배송 정보 등록 시각 UNIX timestamp

400

필수 파라메터가 누락되거나 (PG사별로 필수 여부가 다를 수 있음), 지원하는 않는 PG사인 경우

401

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

404

배송정보를 수정할 거래건이 존재하지 않음

405

POST요청이 아닌 경우

409

해당거래건은 배송정보를 수정할 수 없는 경우

500

배송정보 수정 도중 오류 발생
try
Request
Response Status: N/A
N/A
post/escrows/logis/{imp_uid}

배송정보 단건등록 API

에스크로 결제 건에 대한 배송정보 등록(2-depth의 json으로 Request Body가 구성되어야 합니다)

logis는 하위 필드가 모두 필수입니다.
sender, receiver의 각 세부 항목은 PG사마다 필수 여부가 모두 다릅니다.

지원되는 PG사

  • KG이니시스
  • NHN KCP
  • 키움페이(구 다우, 페이조아)(다우테이타)
  • KSNET
  • 스마트로 - 신모듈(PG사와의 사전 계약이 반드시 필요합니다.)
  • (신) 나이스페이
  • 웰컴페이먼츠

Request

Path

imp_uid: string
포트원 거래고유번호

배송정보를 등록하고자 하는 에스크로 결제건의 포트원 거래고유번호

Body

sender: EscrowLogisSenderAnnotation
발신자 정보

배송을 보내는 발신자의 정보(이름, 연락처, 주소, 우편번호, 발신자와의 관계)

receiver: EscrowLogisReceiverAnnotation
수신자 정보

배송을 받는 수신자의 정보(이름, 연락처, 주소, 우편번호)

logis: EscrowLogisInfoAnnotation
배송정보

택배사코드표는 매뉴얼 참조

products?: EscrowLogisProductsAnnotation[]
배송 상품 정보
(Optional)

배송 보내는 상품의 정보(고유 아이디, 이름, 고유 코드, 통화코드, 수량, 카테고리)

id: string
상품 고유 아이디
name: string
상품 이름
code?: string
상품 코드
(Optional)

가맹점에서 사용하는 상품 관리 코드

amount: number
상품 단위 가격
currency?: string
상품의 결제통화 구분코드
(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

quantity?: integer
상품의 수량
(Optional)

상품의 수량으로 기본값은 1입니다.

tag?: string
상품의 카테고리
(Optional)

상품의 카테고리 e.g) 도서, 가전기기, 인테리어 용품 등

send_email?: boolean
구매확정 시 Email 전송여부
(Optional)

에스크로 구매 확정시 결제 창에 입력했던 이메일로 해당 사실을 전송할지 여부 (기본값 : true)

Response

200

등록 완료
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
company: string
택배사코드

에스크로 결제건의 택배사 코드

invoice: string
송장번호

에스크로 결제건의 송장번호

sent_at: integer
발송 시각

에스크로 결제건의 배송 발송 시각 UNIX timestamp

applied_at: integer
등록 시각

에스크로 결제건의 배송 정보 등록 시각 UNIX timestamp

400

필수 파라메터가 누락되거나 (PG사별로 필수 여부가 다를 수 있음), 지원하는 않는 PG사인 경우

401

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

404

배송정보를 등록할 거래건이 존재하지 않음

405

POST요청이 아닌 경우

409

이미 배송정보 등록이 완료됨, 해당거래건은 배송정보를 등록할 수 없는경우

500

배송정보 등록 도중 오류 발생
try
Request
Response Status: N/A
N/A

가맹점 정보 관련 API

가맹점 정보를 관리하는 기능을 제공합니다.

가맹점의 하위가맹점 관련 API

대표가맹점에 대한 하위가맹점 관리와 관련된 기능을 제공합니다.

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

금융결제원 기준 카드사, 은행의 표준 코드와 기관정보 조회 기능을 제공합니다.

편의점 결제 관련 API

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

타입 정의

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