PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
V1 API hostname: api.iamport.kr
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
API 키와 API 시크릿 확인하기
API 키와 API 시크릿 확인하기
- 관리자 콘솔
상점・계정 관리화면 접속 내 식별코드・API Keys버튼 클릭
API 시크릿은 절대로 외부에 노출되어서는 안되는 값입니다.
실제 구현에서 액세스 토큰 발급은 꼭 서버사이드에서 해주세요.
액세스 토큰 발급 받기
액세스 토큰 발급 받기
포트원 REST API 서버는 Google Public NTP의 시간과 동기화되고 있습니다.
하위 상점 연동을 할 경우 액세스 토큰을 발급받을 때 Agent 계정의 API 키 와 API 시크릿을 사용해야 합니다.
액세스 토큰 사용하기
액세스 토큰 사용하기
발급받은 액세스 토큰은 다른 API를 호출할 때
Authorization 헤더에 Bearer <액세스 토큰> 형식의 값을 넣어주면 됩니다.
자세한 내용은 MDN - HTTP 인증 문서를 참고해주세요.
액세스 토큰 만료기한 연장
액세스 토큰 만료기한 연장
만료된 액세스 토큰으로 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
get/payments/{imp_uid}/balance결제내역 단건조회 API
get/payments/{imp_uid}결제내역 복수조회 API
get/payments결제 단건조회(고유 가맹점 주문번호 조회) API
get/payments/find/{merchant_uid}/{payment_status}결제 복수조회(가맹점 주문번호 중복 포함) API
get/payments/findAll/{merchant_uid}/{payment_status}결제상태기준 복수조회 API
get/payments/status/{payment_status}결제취소 API
post/payments/cancel결제 금액 사전 등록 관련 API
사전 등록하는 결제금액과 관련된 기능을 제공합니다.
비인증 결제 관련 API
별도 결제창 호출없이 결제를 진행할 수 있는 비인증 결제 기능을 제공합니다.
정기 결제 관련 API
비인증 결제 중 정기 결제를 관리하는 기능을 제공합니다.
목차
결제예약 복수조회 API
get/subscribe/payments/schedule결제 예약 API
post/subscribe/payments/schedule결제 예약취소 API
post/subscribe/payments/unschedule결제예약 단건조회 API
get/subscribe/payments/schedule/{merchant_uid}결제요청 예약시각 수정 API
put/subscribe/payments/schedule/{merchant_uid}결제 실패 재예약 API
post/subscribe/payments/schedule/{merchant_uid}/reschedule결제 실패 재시도 API
post/subscribe/payments/schedule/{merchant_uid}/retry결제예약 복수조회(빌링키) API
get/subscribe/payments/schedule/customers/{customer_uid}빌링키 관련 API
빌링키 관리와 관련된 기능을 제공합니다.
목차
빌링키 정보 복수조회 API
get/subscribe/customers빌링키 정보 단건조회 API
get/subscribe/customers/{customer_uid}빌링키 발급 API
post/subscribe/customers/{customer_uid}빌링키 삭제 API
delete/subscribe/customers/{customer_uid}빌링키 결제 복수조회 API (빌링키 결제 내역 확인)
get/subscribe/customers/{customer_uid}/payments빌링키 결제예약 조회 API
get/subscribe/customers/{customer_uid}/schedules가상계좌 관련 API
PG사 관련 API
PG사 별 추가로 지원하는 기능을 제공합니다.
카카오 관련 API
카카오페이에서 지원하는 기능을 제공합니다.
KCP 퀵페이 관련 API
KCP 퀵페이에서 지원하는 기능을 제공합니다.
페이코 관련 API
페이코에서 지원하는 기능을 제공합니다.
페이먼트월 관련 API
페이먼트월에서 지원하는 기능을 제공합니다.
본인인증 관련 API
현금영수증 관련 API
포트원 결제건 및 외부 결제 건의 현금영수증 관리와 관련된 기능을 제공합니다.
에스크로 관련 API
에스크로 결제 건의 배송 정보와 관련된 기능을 제공합니다.
가맹점 정보 관련 API
가맹점 정보를 관리하는 기능을 제공합니다.
가맹점의 하위가맹점 관련 API
하위 상점 관련 API
하위 상점과 관련된 기능을 제공합니다.
post/partners/receipts/{imp_uid}
영수증 내 하위 상점 거래 등록 API
결제 내역 매출전표에 하위 상점의 거래를 등록할 수 있는 API입니다.
지원되는 PG사
- KG이니시스 (이용 전 콘솔 -> 결제연동 탭에서 INIApi Key 등록 필요)
Request
Path
imp_uid: string
포트원 거래고유번호
하위 상점 거래를 등록할 결제건의 포트원 거래고유번호
Body
등록할 하위 상점 및 하위 상점 별 거래 금액 정보
imp_uid에 매핑되는 거래 하위를 구성하는 하위 상점 및 하위 상점 별 거래 금액 정보의 배열
business_registration_number: string
하위 상점 사업자 등록 번호
거래를 구성하는 하위 상점의 사업자 등록 점번호 ("-" 포함)
company_name: string
하위 상점 명
거래를 구성하는 하위 상점의 상점 명
amount: number
하위 상점 거래 금액
거래를 구성하는 하위 상점의 해당 결제건 내 거래 금액
tax_free?: number
하위 상점 거래 금액 중 면세 금액
(Optional)
거래를 구성하는 하위 상점의 해당 결제건 내 면세 금액
vat_amount?: number
하위 상점 거래 금액 중 부가세 금액
(Optional)
거래를 구성하는 하위 상점의 해당 결제건 내 부가세 금액
Response
200
정상적으로 하위 상점 거래 등록이 완료되었습니다.
code?: integer
응답코드
(Optional)
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
message?: string
응답메세지
(Optional)
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
(Optional)
receipt_url?: string
매출전표 확인 URL
(Optional)
거래건에 대한 매출전표를 확인할 수 있는 URL
400
필수 파라미터 누락, 결제 미승인, PG사로부터 요청 실패 응답을 받은 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
결제내역 검색 실패, 결제건에 등록되어있는 결제연동 내역이 확인 불가한 경우
500
포트원 내부 이슈로 인한 API 호출 실패
501
지원하지 않는 PG사
try
Request
Response Status: N/A
N/A
기타 API
부가적인 기능을 제공합니다.
베네피아 포인트 관련 API
베네피아 포인트(복지 포인트)와 관련된 기능을 제공합니다.
결제기관 관련 API
금융결제원 기준 카드사, 은행의 표준 코드와 기관정보 조회 기능을 제공합니다.
편의점 결제 관련 API
편의점 결제를 위한 수납 번호(barcode)와 관련된 기능을 제공합니다.
타입 정의
API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
AuthAnnotationAuthResponseBenepiaPointAnnotationBenepiaPointResponseCertificationAnnotationCertificationOTPAnnotationCertificationOTPResponseCertificationResponseCustomerAnnotationCustomerResponseEscrowLogisAnnotationEscrowLogisInfoAnnotationEscrowLogisProductsAnnotationEscrowLogisReceiverAnnotationEscrowLogisResponseEscrowLogisSenderAnnotationExternalReceiptAnnotationExternalReceiptResponseKakaoOrderAnnotationKakaoOrderResponseKcpQuickMemberAnnotationKcpQuickMemberResponseMultipleCustomersResponseMultiplePaymentsResponseMultiplePgSettingResponseNaverAddressNaverCashAmountAnnotationNaverCashAmountResponseNaverOrdererNaverProductOrderAnnotationNaverProductOrderArrayResponseNaverProductOrderResponseNaverReviewAnnotationNaverReviewsResponsePagedPaymentAnnotationPartnerReceiptResponsePartnerReceiptResultAnnotationPartnerReceiptsAnnotationPaycoStatusAnnotationPaycoStatusResponsePaymentAnnotationPaymentBalanceAnnotationPaymentBalanceHistoriesAnnotationPaymentBalanceResponsePaymentBalanceResponseAnnotationPaymentCancelAnnotationPaymentListResponsePaymentPrepareAnnotationPaymentPrepareResponsePaymentResponsePaymentwallDeliveryAnnotationPaymentwallDeliveryDetailAnnotationPgSettingAnnotationReceiptAnnotationReceiptResponseResponseAnnotationScheduleAnnotationScheduleResponseScheduleResultAnnotationSingleScheduleResponseStandardCodeAnnotationStandardCodeListResponseStandardCodeResponseSubscribePaymentExtraTierAnnotationTierResponseVbankHolderAnnotationVbankHolderResponse