개발자센터

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

인증 관련 API

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

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

결제 관련 API

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

결제 금액 사전 등록 관련 API

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

비인증 결제 관련 API

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

정기 결제 관련 API

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

빌링키 관련 API

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

가상계좌 관련 API

가상계좌 결제와 관련된 기능을 제공합니다.
post/vbanks

가상계좌 발급 API

가상계좌번호를 발급하여 고객이 입금할 수 있도록 합니다.
희망하시는 은행, 예금주명으로 입금이 가능한 가상계좌를 생성할 수 있습니다.(별도로 PG계약 필요)
은행구분코드는 페이지 가장 하단에 있는 은행코드표를 참조하시기 바랍니다.

지원되는 PG사

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

Request

Query

pg_api_key?: string
Api Key

가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. (이니시스 전용 필수 파라미터로 Query parameter입니다.)

Body

merchant_uid: string
고객사 주문번호

가상계좌를 발급할 결제건의 고객사 거래 고유번호으로 이미 결제가 이뤄진 적이 있는 merchant_uid로는 추가적인 가상계좌 생성이 불가능합니다.

amount: number
입금 예정 금액

발급 된 가상계좌에 입금 될 금액

product_type?: "real" | "digital"
상품구분

가상계좌 발급을 위한 결제건의 상품구분 코드

vbank_num?: string
고정 가상 계좌 번호

고정식 가상계좌 발급 시, pg사로부터 전달받은 가상계좌 번호 (사용을 위해 PG사와 협의 필요)

vbank_code: string
은행구분코드

은행구분코드 리스트 확인하기

vbank_due: integer
가상계좌 입금기한

가상계좌 발급시 입금기한 UNIX TIMESTAMP

vbank_holder?: string
가상계좌 예금주명

가상계좌 발급을 위한 예금주명

vbank_key?: string
계좌 고유 키

고정식 가상계좌를 발급받기 위한 고객과 매칭시킨 계좌 고유 키(사용을 위해 PG사와 협의 필요)

name?: string
주문명

가상계좌 발급을 위한 결제건의 주문명

buyer_name?: string
주문자명

가상계좌 발급을 위한 결제건의 주문자명

buyer_email?: string
주문자 Email 주소

가상계좌 발급을 위한 결제건의 주문자 Email주소

buyer_tel?: string
주문자 전화번호

가상계좌 발급을 위한 결제건의 주문자 전화번호

business_registration_number?: string
사업자 등록번호

주문자의 사업자 등록번호

buyer_addr?: string
주문자 주소

가상계좌 발급을 위한 결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호

가상계좌 발급을 위한 결제건의 주문자 우편번호

pg?: string
PG사 구분코드

가상계좌 발급 할 PG사 구분코드

notice_url?: array
Notification URL(Webhook URL)

가상계좌 입금시 입금통지받을 URL

custom_data?: string
추가 정보

결제정보와 함께 저장할 추가정보로 객체로 전달되는 경우 JSON 문자열로 저장

tax_free?: integer
면세금액

가상계좌 발급을 위한 결제건의 면세금액

vat_amount?: number
부가세

가상계좌 발급을 위한 결제건의 부가세 금액

product_count?: integer
결제 상품의 개수

가상계좌 발급을 위한 결제 상품의 개수로 기본값은 1입니다

escrow_password?: string
에스크로 비밀번호

헥토파이낸셜 고정식 가상계좌 에스크로 결제 시 필수로 입력해야합니다.

fixed_unlimited_vbank?: boolean
고정식 무제한 가상계좌 여부

헥토파이낸셜 고정식 무제한 가상계좌 발급시 필수로 입력해야합니다.

Response

200 Ok

가상계좌 생성 완료

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: PaymentAnnotation

401 Error

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

try
Request
Request Sample
N/A
put/vbanks/{imp_uid}

가상계좌 발급정보 수정 API

API요청으로 발급된 가상계좌(입금이 되기 전)의 정보를 수정합니다
아직 입금이 되지 않은 가상계좌의 입금기한 또는 입금금액을 수정할 수 있습니다. (헥토파이낸셜(구 세틀뱅크)만 사용 가능)
imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 수정이 가능합니다)

Request

Path

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

가상계봐 발급 정보를 수정할 결제건의 포트원 거래고유번호

Body

amount?: integer
발급금액

수정할 결제금액

vbank_due?: integer
입금기한

수정할 가상계좌 입금기한 UNIX TIMESTAMP

Response

200 Ok

가상계좌 수정 완료

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: PaymentAnnotation

400 Error

imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우/ 가상계좌가 입금대기 상태(ready)가 아닌 경우

401 Error

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

404 Error

유효하지 않은 imp_uid

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

가상계좌 발급취소 API

발급된 가상계좌(입금이 되기 전)를 말소합니다.
아직 입금이 되지 않은 가상계좌를 말소시킴으로써 구매자가 실수로 입금하는 경우를 방지하도록 합니다.
imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 말소가 가능합니다)

지원되는 PG사

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

Request

Path

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

가상계좌 발급 취소할 결제건의 포트원 거래고유번호

Query

pg_api_key?: string
API Key

가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. (이니시스 전용 필수 파라미터로 Query parameter입니다.)

Response

200 Ok

가상계좌 말소 완료

code?: integer
응답코드

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

message?: string
응답메세지

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

response?: PaymentAnnotation

400 Error

imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우 / 가상계좌가 입금대기 상태(ready)가 아닌 경우

401 Error

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

404 Error

유효하지 않은 imp_uid

try
Request
Request Sample
N/A

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