개발자센터

PortOne REST API - V1

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

2024년 9월 1일부로 포트원 V1 API에 대해 일부 보안 규격이 지원 종료됩니다.
자세한 사항은TLS 지원 범위를 참고해주세요.

V1 API hostname: api.iamport.kr

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


하위호환성

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

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

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

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

      • 오로지 선택 입력 정보만 추가될 수 있습니다.
    • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
    • enum 타입의 값이 삭제되지 않습니다.

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

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

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

      • 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
      • 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
    • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.

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

      • 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
      • 새로운 필드 및 값이 추가되는 경우 사전 공지를 통해 안내드립니다.

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

인증 관련 API

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

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

결제 관련 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

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

발급내역 단건 조회 API

포트원을 통해 발행된 현금영수증 상세정보를 조회하는 API입니다.

Request

Path

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

Response

200

현금영수증 상세정보 조회 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
response?: ReceiptAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

401

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

404

존재하지 않는 포트원 거래정보이거나 현금영수증 발행된 내역이 확인되지 않는 경우

try
Request
Request Sample
N/A
post/receipts/{imp_uid}

현금영수증 단건발급 API

포트원을 통해 발생된 현금성 거래(가상계좌, 계좌이체)의 포트원 거래고유번호(imp_uid)를 기준으로 현금영수증이 발급 됩니다.
imp_uid 거래를 처리하는데 사용된 PG설정값을 그대로 활용합니다.
(ex. KCP 거래건이면 KCP를 통해 현금영수증 발행 API처리)
현금영수증 발급 금액은 현금성 거래의 금액으로 자동 적용됩니다. 부분취소된 거래인 경우 남은 잔액으로 발급됩니다.

지원되는 PG사

  • KG 이니시스
  • NHN KCP
  • 나이스페이먼츠
  • KICC
  • 헥토파이낸셜(구 세틀뱅크)
  • 키움페이(구 다우, 페이조아)
  • 토스페이먼츠 - 신모듈
  • KSNET
  • 스마트로 - 신모듈
  • (신) 나이스페이
  • 웰컴페이먼츠

Request

Path

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

Body

product_type?: string
주문 상품구분
(Optional)
real
digital
identifier: string
식별정보
identifier_type?: string
식별정보 구분코드
(Optional)
person
business
phone
taxcard
type?: string
타입(대상)
(Optional)
person
company
company_tel?: string
고객센터 번호
(Optional)
company_name?: string
상점 사업자 명
(Optional)
corp_reg_no?: string
상점 사업자 번호
(Optional)
buyer_name?: string
구매자 이름
(Optional)

현금영수증을 발행할 결제건의 구매자 이름

buyer_email?: string
구매자 Email 주소
(Optional)
buyer_tel?: string
구매자 전화번호
(Optional)

현금영수증을 발행할 결제건의 구매자 전화번호

tax_free?: integer
면세금액
(Optional)

현금영수증 발행금액 중 면세금액으로 지정하지 않으면 0원으로 적용합니다.

vat?: integer
(Optional) (Deprecated)

Deprecated 되었으므로 tax_free 파라메터를 사용해주세요.부가세(지정하지 않으면 공급가액의 10%로 자동 적용)

vat_amount?: number
부가세 지정 금액
(Optional)

Response

200

현금영수증 발행 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
response?: ReceiptAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

400

필수 파라메터가 누락된 경우, 결제완료(paid)가 아닌 결제 건에 대해 발행요청한 경우, 이미 현금영수증 발행된 건에 대해 요청한 경우

401

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

500

현금영수증 발행에 실패한 경우

501

현재 포트원이 현금영수증 관련 지원하지 않는 PG사인 경우

try
Request
Request Sample
N/A
delete/receipts/{imp_uid}

포트원 발급분 취소 API

포트원을 통해 발급한 현금영수증 발급거래를 취소합니다
포트원과 별개로 거래된 현금영수증 취소는 DELETE 외부 발급분 취소 API를 이용해주세요.

지원되는 PG사

  • KG 이니시스
  • NHN KCP
  • 헥토파이낸셜(구 세틀뱅크)
  • 나이스페이먼츠
  • 키움페이(구 다우, 페이조아)
  • 토스페이먼츠 - 신모듈
  • (신) 나이스페이
  • KSNET
  • 스마트로 - 신모듈
  • 웰컴페이먼츠

Request

Path

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

Response

200

현금영수증 발급취소 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
response?: ReceiptAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

400

포트원으로 현금영수증이 발급된 적 없는 건에 대해서 발급취소 요청한 경우

401

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

500

PG사로부터 현금영수증 발급취소 실패응답을 받은 경우

501

현재 포트원이 현금영수증 관련 지원하지 않는 PG사인 경우

try
Request
Request Sample
N/A
get/receipts/external/{merchant_uid}

외부 발급내역 단건 조회 API

포트원 API를 통해 현금영수증만 발행된 건의 상세정보를 조회하는 API입니다. (포트원과 별개로 결제된 현금거래건)

Request

Path

merchant_uid: string
고객사 주문번호

Response

200

현금영수증 상세정보 조회 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
(Optional)
merchant_uid: string
고객사 주문번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

401

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

404

merchant_uid 로 현금영수증 발행된 내역이 확인되지 않는 경우

try
Request
Request Sample
N/A
post/receipts/external/{merchant_uid}

현금영수증 발급(외부) API

포트원과 별개로 거래된 일반 현금결제에 대해, 포트원 내에 설정된 PG사로 현금영수증 발행 요청하는 API입니다.

지원되는 PG사

  • KG이니시스
  • NHN KCP
  • 나이스페이먼츠
  • KICC
  • 헥토파이낸셜(구 세틀뱅크)
  • 토스페이먼츠 - 신모듈
  • KSNET
  • 스마트로 - 신모듈
  • (신) 나이스페이
  • 웰컴페이먼츠

Request

Path

merchant_uid: string
고객사 주문번호

현금영수증 발행을 위한 고객사 주문번호

Body

name: string
주문명
amount: integer
발행 금액
product_type?: string
주문 상품구분
(Optional)
real
digital
identifier: string
식별정보
identifier_type?: string
식별정보 구분코드
(Optional)
person
business
phone
taxcard
type?: string
타입(대상)
(Optional)
person
company
buyer_name?: string
구매자 이름
(Optional)

현금영수증을 발행할 결제건의 구매자 이름

buyer_email?: string
구매자 Email 주소
(Optional)
buyer_tel?: string
구매자 전화번호
(Optional)

현금영수증을 발행할 결제건의 구매자 전화번호

tax_free?: integer
면세금액
(Optional)

현금영수증 발행금액 중 면세금액으로 지정하지 않으면 0원으로 적용

pg?: string
PG 구분코드
(Optional)
vat_amount?: number
부가세 지정 금액
(Optional)
corp_reg_no?: string
상점 사업자 번호
(Optional)
pay_method?: string
결제수단
(Optional)
trans
vbank

Response

200

현금영수증 발행 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
(Optional)
merchant_uid: string
고객사 주문번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

400

필수 파라메터가 누락된 경우, 이미 현금영수증 발행된 merchant_uid 에 대해 요청한 경우

401

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

500

현금영수증 발행에 실패한 경우

501

현재 포트원이 현금영수증 관련 지원하지 않는 PG사인 경우

try
Request
Request Sample
N/A
delete/receipts/external/{merchant_uid}

외부 발급분 취소 API

포트원과 별개로 거래된 일반 현금결제에 대해, 포트원 내에 설정된 PG사로 포트원 API를 이용해 현금영수증 발행취소하는 API입니다.

지원되는 PG사

  • KG이니시스
  • NHN KCP
  • 헥토파이낸셜(구 세틀뱅크)
  • 나이스페이먼츠
  • 토스페이먼츠 - 신모듈
  • KSNET
  • 스마트로 - 신모듈
  • (신) 나이스페이
  • 웰컴페이먼츠

Request

Path

merchant_uid: string
고객사 주문번호

발급취소대상 고객사 주문번호

Response

200

현금영수증 발행취소 완료

code?: integer
응답코드
(Optional)
message?: string
응답메세지
(Optional)
(Optional)
merchant_uid: string
고객사 주문번호
receipt_tid?: string
PG사 현금영수증 발행 고유번호
(Optional)
apply_num: string
국세청 발행번호
type: string
타입(대상)
amount: integer
발행 금액
vat: integer
부가세액
receipt_url?: string
현금영수증 URL
(Optional)
applied_at: integer
발행시각
cancelled_at?: integer
발행취소시각
(Optional)

400

merchant_uid 파라메터가 누락된 경우

401

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

404

현금영수증 발행된 적이 없는 merchant_uid 에 대해 요청한 경우

500

현금영수증 발행취소에 실패한 경우

501

현재 포트원이 현금영수증 관련 지원하지 않는 PG사인 경우

try
Request
Request Sample
N/A

에스크로 관련 API

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

고객사 정보 관련 API

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

고객사의 하위 상점 관련 API

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

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

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

편의점 결제 관련 API

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

타입 정의

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