개발자센터
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

본인인증 요청 및 결과 조회와 관련된 기능을 제공합니다.
get/certifications/{imp_uid}

본인인증 결과조회 API

본인인증된 결과를 imp_uid를 이용하여 조회합니다.

Request

Path

imp_uid: string
포트원 인증 고유번호

본인인증 결과로 리턴 받은 포트원 인증 고유번호

Response

200

본인인증결과 조회 성공
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
imp_uid: string
포트원 인증 고유번호

본인인증 결과건의 포트원 인증 고유번호

merchant_uid?: string
가맹점 주문번호
(Optional)

본인인증 결과건의 포트원 가맹점 주문번호

pg_tid?: string
PG사 본인인증결과 고유번호
(Optional)

본인인증 결과건의 PG사 본인인증결과 고유번호

pg_provider: string
pg사 구분코드

본인인증 제공 PG사의 명칭

name?: string
성명
(Optional)

인증된 사용자의 성명

gender?: string
성별
(Optional)

인증된 사용자의 성별

birthday?: string
생년월일
(Optional)

인증된 사용자의 생년월일 ISO8601 형식의 문자열. YYYY-MM-DD 10자리 문자열

foreigner: boolean
외국인 여부

다날 본인인증서비스 계약시 외국인 구분기능을 추가 요청하지 않은 경우 항상 false를 응답합니다.

  • true : 외국인
  • false : 내국인
phone?: string
휴대폰번호
(Optional)

특수 기호없이 숫자로만 구성된 휴대폰번호가 전달되며 통신사 사전승인이 이뤄지지 않으면 phone 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

carrier?: string
통신사
(Optional)

통신사 사전승인이 이뤄지지 않으면 carrier 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

  • SKT
  • KT
  • LGT
  • SKT_MVNO
  • KT_MVNO
  • LGT_MVNO
certified?: boolean
인증성공여부
(Optional)

본인인증 성공여부

certified_at?: integer
인증처리시각
(Optional)

본인인증 처리시각 UNIX timestamp

unique_key?: string
개인 고유구분 식별키
(Optional)

개인별로 고유하게 부여하는 개인 식별키(CI)

unique_in_site?: string
가맹점 내 개인 고유구분 식별키
(Optional)

본인인증 PG MID별로 할당되는 개인 식별키

origin?: string
웹 페이지 URL
(Optional)

본인인증 프로세스가 진행된 웹 페이지의 URL

foreigner_v2?: boolean
외국인 여부(nullable)
(Optional)

다날 본인인증서비스 계약시 외국인 구분기능 추가 요청을 해주셔야 사용이 가능합니다. 요청을 하지 않은 경우 null을 응답합니다.

  • true:외국인
  • false:내국인

401

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

404

본인인증결과를 찾을 수 없음
try
Request
Response Status: N/A
N/A
delete/certifications/{imp_uid}

본인인증 정보삭제 API

본인인증 결과를 삭제합니다.
본인인증 결과정보를 포트원 서버내에서 완전히 삭제하고 싶을 때 요청합니다.

Request

Path

imp_uid: string
포트원 인증 고유번호

본인인증 결과로 리턴받은 포트원 인증 고유번호

Response

200

본인인증결과 삭제 완료
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
imp_uid: string
포트원 인증 고유번호

본인인증 결과건의 포트원 인증 고유번호

merchant_uid?: string
가맹점 주문번호
(Optional)

본인인증 결과건의 포트원 가맹점 주문번호

pg_tid?: string
PG사 본인인증결과 고유번호
(Optional)

본인인증 결과건의 PG사 본인인증결과 고유번호

pg_provider: string
pg사 구분코드

본인인증 제공 PG사의 명칭

name?: string
성명
(Optional)

인증된 사용자의 성명

gender?: string
성별
(Optional)

인증된 사용자의 성별

birthday?: string
생년월일
(Optional)

인증된 사용자의 생년월일 ISO8601 형식의 문자열. YYYY-MM-DD 10자리 문자열

foreigner: boolean
외국인 여부

다날 본인인증서비스 계약시 외국인 구분기능을 추가 요청하지 않은 경우 항상 false를 응답합니다.

  • true : 외국인
  • false : 내국인
phone?: string
휴대폰번호
(Optional)

특수 기호없이 숫자로만 구성된 휴대폰번호가 전달되며 통신사 사전승인이 이뤄지지 않으면 phone 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

carrier?: string
통신사
(Optional)

통신사 사전승인이 이뤄지지 않으면 carrier 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

  • SKT
  • KT
  • LGT
  • SKT_MVNO
  • KT_MVNO
  • LGT_MVNO
certified?: boolean
인증성공여부
(Optional)

본인인증 성공여부

certified_at?: integer
인증처리시각
(Optional)

본인인증 처리시각 UNIX timestamp

unique_key?: string
개인 고유구분 식별키
(Optional)

개인별로 고유하게 부여하는 개인 식별키(CI)

unique_in_site?: string
가맹점 내 개인 고유구분 식별키
(Optional)

본인인증 PG MID별로 할당되는 개인 식별키

origin?: string
웹 페이지 URL
(Optional)

본인인증 프로세스가 진행된 웹 페이지의 URL

foreigner_v2?: boolean
외국인 여부(nullable)
(Optional)

다날 본인인증서비스 계약시 외국인 구분기능 추가 요청을 해주셔야 사용이 가능합니다. 요청을 하지 않은 경우 null을 응답합니다.

  • true:외국인
  • false:내국인

401

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

404

본인인증결과를 찾을 수 없음

500

DB삭제도중 서버 장애 발생
try
Request
Response Status: N/A
N/A
post/certifications/otp/request

본인인증 요청 API

사용자 개인정보를 API로 전달하여, 통신사로부터 확인되는 경우 OTP(6자리 인증번호)를 사용자에게 SMS로 전달합니다.

통신사 승인을 받은 일부 가맹점에 한해 사용하실 수 있으며, 현재 다날을 통해서만 서비스되고 있습니다.

본인인증 대상자의 성명, 생년월일 + 주민등록 뒷부분 첫 자리, 휴대폰번호, 통신사 정보를 가맹점에서 직접 입력받아 API요청하면 됩니다. 전달된 개인정보가 올바를 경우 해당 휴대폰으로 인증번호 SMS가 전송됩니다.

200응답 시 imp_uid 가 응답데이터로 전달되며, SMS전송된 인증번호를 본인인증 완료 API 로 요청주시면 최종 본인인증 프로세스가 완료됩니다.

Request

Body

name: string
성명

본인인증 대상자 성명

phone: string
휴대폰번호
  • 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리
birth: string
생년월일

YYMMDD 6자리(연/월/일 사이에 - 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리함)

gender_digit: string
성별구분코드

주민등록번호 13자리 중 7번째 자리

2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4

carrier: string
통신사구분코드

알뜰폰 사용자의 경우, carrier파라메터 SKT, KT, LGT 중 하나를 지정한 후 is_mvno : true 로 설정

  • SKT
  • KT
  • LGT
is_mvno?: boolean
알뜰폰 사용 여부
(Optional)

본인인증 대상자 알뜰폰 사용 여부

company?: string
가맹점 서비스명칭
(Optional)

KISA에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭

merchant_uid?: string
가맹점 주문번호
(Optional)

본인인증 요청건을 식별하기 위한 가맹점 주문번호

pg?: string
PG사 구분코드
(Optional)

다날 상점아이디를 2개 이상 동시에 사용하시려는 경우 설정하시면 됩니다. danal.{상점아이디} 형태로 지정

Response

200

본인인증을 위한 대상자 정보 검증 완료(인증번호 SMS전송요청 중)
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
imp_uid: string
포트원 인증 고유번호

본인인증 결과건의 포트원 인증 고유번호

400

대상자 개인정보 중 일부가 누락되었거나 올바르지 않은 경우

401

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

500

처리 중 다날서버 응답오류 등 오류가 발생한 경우
try
Request
Response Status: N/A
N/A
post/certifications/otp/confirm/{imp_uid}

본인인증 완료 API

본인인증 요청 API를 통해 SMS로 전송된 인증번호를 전달하여 본인인증을 완료합니다.
본인인증이 완료되면 대상자의 이름, 전화번호, 통신사, 성별, 외국인 여부, 생년월일, CI, DI 값을 응답받을 수 있습니다.

Request

Path

imp_uid: string
포트원 인증 고유번호

본인인증 요청 API 요청 후 응답된 인증 고유번호

Body

otp: string
본인인증 번호

SMS로 전송된 본인인증 번호

Response

200

본인인증완료
code?: integer
응답코드
(Optional)

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

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

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

(Optional)
imp_uid: string
포트원 인증 고유번호

본인인증 결과건의 포트원 인증 고유번호

merchant_uid?: string
가맹점 주문번호
(Optional)

본인인증 결과건의 포트원 가맹점 주문번호

pg_tid?: string
PG사 본인인증결과 고유번호
(Optional)

본인인증 결과건의 PG사 본인인증결과 고유번호

pg_provider: string
pg사 구분코드

본인인증 제공 PG사의 명칭

name?: string
성명
(Optional)

인증된 사용자의 성명

gender?: string
성별
(Optional)

인증된 사용자의 성별

birthday?: string
생년월일
(Optional)

인증된 사용자의 생년월일 ISO8601 형식의 문자열. YYYY-MM-DD 10자리 문자열

foreigner: boolean
외국인 여부

다날 본인인증서비스 계약시 외국인 구분기능을 추가 요청하지 않은 경우 항상 false를 응답합니다.

  • true : 외국인
  • false : 내국인
phone?: string
휴대폰번호
(Optional)

특수 기호없이 숫자로만 구성된 휴대폰번호가 전달되며 통신사 사전승인이 이뤄지지 않으면 phone 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

carrier?: string
통신사
(Optional)

통신사 사전승인이 이뤄지지 않으면 carrier 속성은 존재하지 않습니다.

통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.

  • SKT
  • KT
  • LGT
  • SKT_MVNO
  • KT_MVNO
  • LGT_MVNO
certified?: boolean
인증성공여부
(Optional)

본인인증 성공여부

certified_at?: integer
인증처리시각
(Optional)

본인인증 처리시각 UNIX timestamp

unique_key?: string
개인 고유구분 식별키
(Optional)

개인별로 고유하게 부여하는 개인 식별키(CI)

unique_in_site?: string
가맹점 내 개인 고유구분 식별키
(Optional)

본인인증 PG MID별로 할당되는 개인 식별키

origin?: string
웹 페이지 URL
(Optional)

본인인증 프로세스가 진행된 웹 페이지의 URL

foreigner_v2?: boolean
외국인 여부(nullable)
(Optional)

다날 본인인증서비스 계약시 외국인 구분기능 추가 요청을 해주셔야 사용이 가능합니다. 요청을 하지 않은 경우 null을 응답합니다.

  • true:외국인
  • false:내국인

400

인증번호를 누락하였거나 이미 인증처리가 완료된 건에 대해 재요청하는 경우

401

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

404

imp_uid 에 해당되는 요청건이 없는 경우

500

처리 중 다날서버 응답오류 등 오류가 발생한 경우
try
Request
Response Status: N/A
N/A

현금영수증 관련 API

포트원 결제건 및 외부 결제 건의 현금영수증 관리와 관련된 기능을 제공합니다.

에스크로 관련 API

에스크로 결제 건의 배송 정보와 관련된 기능을 제공합니다.

가맹점 정보 관련 API

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

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

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

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

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

편의점 결제 관련 API

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

타입 정의

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