개발자센터

PortOne REST API - V1

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

2026년 1월 26일부로 포트원 V1 결제내역 단건조회 API에 동작 변경이 있습니다.

자세한 사항은 V1 결제내역 단건조회 API 동작 변경 안내를 참고해주세요.

V1 API hostname: api.iamport.kr

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


하위호환성

포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.

  1. 현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.

    • 입력 형식 내 필드 정의가 삭제되지 않습니다.

    • 필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.

      • 오로지 선택 입력 정보만 추가될 수 있습니다.

    • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.

    • enum 타입의 값이 삭제되지 않습니다.

  2. 출력 형식이 확장될 수 있지만, 축소되지 않습니다.

    • 출력 형식 내 필드 정의가 삭제되지 않습니다.

    • 사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.

      • 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
      • 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.

    • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.

    • 단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.

      • 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.

UNSTABLE이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.

하위 상점의 API 사용

하위 상점에 대해 API를 사용하려는 경우 API 호출 시 Tier 헤더(HTTP Request Header)로 하위상점의 티어코드를 전달해야 합니다.
[Agency & Tier 란?]

인증 관련 API

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

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

결제 관련 API

결제 건과 관련된 기능을 제공합니다.

결제 금액 사전 등록 관련 API

사전 등록하는 결제금액과 관련된 기능을 제공합니다.

비인증 결제 관련 API

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

정기 결제 관련 API

비인증 결제 중 정기 결제를 관리하는 기능을 제공합니다.

빌링키 관련 API

빌링키 관리와 관련된 기능을 제공합니다.
get/subscribe/customers

빌링키 정보 복수조회 API

여러 개의 빌링키를 한 번에 조회하는 API입니다.

등록된 카드마다 1개의 customer_uid가 매핑되므로, 고객사 시스템 내에 1명의 고객이 여러 장의 카드를 등록할 수 있는 경우 여러 개의 customer_uid를 가지게 됩니다.
해당 고객이 등록해놓은 카드정보 목록을 한 번에 조회하는데 사용하면 편리합니다.

예시) /subscribe/customers?customer_uid[]=hong_1234_a&customer_uid[]=hong_1234_b

Request

Query

customer_uid[]: Array<string>
구매자의 결제 수단 식별 고유번호

빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호

Response

200 Ok

요청된 모든 customer_uid 에 대한 빌키정보 응답완료. 조회된 빌링키에 따라 일반 빌링키(CustomerAnnotation)와 슈퍼 빌링키(SuperBillingKeyAnnotation)를 포함할 수 있습니다.

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: Array<CustomerAnnotation>

207 Partial Success

요청된 customer_uid 중 일부 빌키정보 조회 실패(ex. 접근권한없음 또는 존재하지 않는 customer_uid). 조회된 빌링키에 따라 일반 빌링키(CustomerAnnotation)와 슈퍼 빌링키(SuperBillingKeyAnnotation)를 포함할 수 있습니다.

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: Array<CustomerAnnotation>

401 Error

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

404 Error

유효하지 않은 customer_uid

try
Request
Request Sample
N/A
get/subscribe/customers/{customer_uid}

빌링키 정보 단건조회 API

구매자의 빌링키 정보 조회

Request

Path

customer_uid: string
구매자의 결제 수단 식별 고유번호

빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호

Response

200 Ok

정상 조회 시, 일반 빌링키 조회는 CustomerResponse를 반환하며, 슈퍼 빌링키 조회는 SuperBillingKeyResponse를 반환합니다.

CustomerResponse?: CustomerResponse

일반 빌링키 응답

SuperBillingKeyResponse?: SuperBillingKeyResponse

슈퍼 빌링키 응답

401 Error

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

404 Error

유효하지 않은 customer_uid

try
Request
Request Sample
N/A
post/subscribe/customers/{customer_uid}

빌링키 발급 API

구매자에 대해 빌링키 발급 및 저장
해당 빌링키 발급 API는 PG사와 협의가 완료된 경우 이용 가능한 서비스입니다.
  • PG사 협의를 통해 카드정보 필수 조건 값 조정이 가능합니다.
  • 민감한 카드정보를 이용하기 때문에 보안에 특히 유의하셔야 합니다.
  • customer_uid 값은 고객 & 카드번호 단위별로 고유하게 발급 관리되어야 합니다

Request

Path

customer_uid: string
구매자의 결제 수단 식별 고유번호

빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호

Body

pg?: string
PG 구분코드

빌링키 발급을 받고자 하는 PG사 구분코드

customer_id?: string
구매자 ID

구매자 식별 고유 번호

card_number: string
카드번호

빌링키 발급 하고자 하는 카드의 번호(dddd-dddd-dddd-dddd)

expiry: string
카드 유효기간

빌링키 발급 하고자 하는 카드 유효기간(YYYY-MM)

birth?: string
생년월일

법인카드의 경우 사업자등록번호10자리

PG사별로 혹은 계약상황에따라 필수값 여부가 상이합니다.

pwd_2digit?: string
카드비밀번호 앞 2자리

PG사별 혹은 계약상황에 따라 필수값 여부가 상이합니다.

cvc?: string
카드 인증번호

빌링키 발급 받고자 하는 카드 카드 뒷면 3자리, AMEX의 경우 4자리

customer_name?: string
카드소유자명

고객(카드소지자) 관리용 성함

customer_tel?: string
카드소유자 연락처

고객(카드소지자) 전화번호

customer_email?: string
카드소유자 이메일주소

고객(카드소지자) Email

customer_addr?: string
카드소유자 주소

고객(카드소지자) 주소

customer_postcode?: string
카드소유자 우편번호

고객(카드소지자) 우편번호

channelGroupId?: string
스마트 라우팅 그룹 ID

스마트 라우팅 그룹 내 활성화 된 모든 채널로 빌링키 발급 요청을 합니다.

Response

200 Ok

정상 등록 시, 일반 빌링키 발급은 CustomerResponse를 반환하며, channelGroupId를 이용한 슈퍼 빌링키 발급은 SuperBillingKeyResponse를 반환합니다.

CustomerResponse?: CustomerResponse

일반 빌링키 응답

SuperBillingKeyResponse?: SuperBillingKeyResponse

슈퍼 빌링키 응답

401 Error

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

try
Request
Request Sample
N/A
delete/subscribe/customers/{customer_uid}

빌링키 삭제 API

구매자의 빌링키 정보 삭제
빌링키 삭제시 결제예약된 내역이 존재하는지 반드시 확인하셔야 합니다.
삭제된 빌링키는 복구할 수 없습니다.

Request

Path

customer_uid: string
구매자의 결제 수단 식별 고유번호

빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호

Query

reason?: string
삭제 사유

빌링키를 삭제하려는 사유

extra[requester]?: string
삭제 요청자

빌링키 삭제 요청자

Response

200 Ok

정상 삭제 시, 일반 빌링키 삭제는 CustomerResponse를 반환하며, 슈퍼 빌링키 삭제는 SuperBillingKeyResponse를 반환합니다.

CustomerResponse?: CustomerResponse

일반 빌링키 응답

SuperBillingKeyResponse?: SuperBillingKeyResponse

슈퍼 빌링키 응답

401 Error

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

404 Error

유효하지 않은 customer_uid

try
Request
Request Sample
N/A
get/subscribe/customers/{customer_uid}/payments

빌링키 결제 복수조회 API (빌링키 결제 내역 확인)

구매자의 빌링키로 결제된 결제목록을 조회합니다.

Request

Path

customer_uid: string
구매자의 결제 수단 식별 고유번호

빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호

Query

page?: integer
조회목록 페이징

조회목록 페이징으로 기본값은 1입니다.

Response

200 Ok

정상 조회

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: PagedPaymentAnnotation

401 Error

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

404 Error

유효하지 않은 customer_uid

try
Request
Request Sample
N/A
get/subscribe/customers/{customer_uid}/schedules

빌링키 결제예약 조회 API

결제예약 복수조회(빌키) API와 동일한 동작을 하는 API입니다.

customer_uid별 결제예약목록을 조회할 수 있습니다. 결제예약정보가 (페이징된)목록으로 전달되며, 최대 3개월 단위로 조회가 가능합니다.

결제예약정보가 예약된 시각 기준으로 최신순으로 정렬되어 전달됩니다.

Request

Path

customer_uid: string
구매자의 결제 수단 식별 고유번호

결제예약에 사용된 구매자의 결제 수단 식별 고유번호

Query

page?: integer
조회목록 페이징

조회목록 페이징으로 기본값은 1입니다.

from: integer
조회 시작시각

unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. from <= '예약시각')

to: integer
조회 종료시각

unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. '예약시각' < to)

schedule-status?: "scheduled" | "executed" | "revoked"
예약상태

조회 하고자 하는 예약 상태

Response

200 Ok

결제예약목록 조회완료

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: Array<ScheduleResultAnnotation>

400 Error

검색 파라메터가 유효하지 않은 경우

401 Error

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

try
Request
Request Sample
N/A

가상계좌 관련 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

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

편의점 결제 관련 API

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

타입 정의

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