PortOne REST API - V1

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

2024년 9월 1일부로 포트원 V1 API에 대해 일부 보안 규격이 지원 종료됩니다.

자세한 사항은 TLS 지원 범위를 참고해주세요.

V1 API hostname: api.iamport.kr


하위호환성

포트원이 제공하는 모든 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

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 Ok

code?: integer
응답코드
message?: string
응답메세지

401 Error

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

404 Error

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

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

본인인증 정보삭제 API

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

Request

Path

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

Response

200 Ok

code?: integer
응답코드
message?: string
응답메세지

401 Error

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

404 Error

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

500 Error

DB삭제도중 서버 장애 발생

try
Request
Request Sample
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
생년월일
gender_digit: string
성별구분코드
carrier: "SKT" | "KT" | "LGT"
통신사구분코드
is_mvno?: boolean
알뜰폰 사용 여부
company?: string
고객사 서비스명칭
merchant_uid?: string
고객사 주문번호
pg?: string
PG사 구분코드

Response

200 Ok

code?: integer
응답코드
message?: string
응답메세지

400 Error

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

401 Error

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

500 Error

처리 중 다날서버 응답오류 등 오류가 발생한 경우

try
Request
Request Sample
N/A
post/certifications/otp/confirm/{imp_uid}

본인인증 완료 API

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

Request

Path

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

Body

otp: string
본인인증 번호

Response

200 Ok

code?: integer
응답코드
message?: string
응답메세지

400 Error

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

401 Error

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

404 Error

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

500 Error

처리 중 다날서버 응답오류 등 오류가 발생한 경우

try
Request
Request Sample
N/A

현금영수증 관련 API

에스크로 관련 API

고객사 정보 관련 API

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

고객사의 하위 상점 관련 API

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

편의점 결제 관련 API

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

타입 정의

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