PortOne REST API - V1

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

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

V1 API hostname: api.iamport.kr

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

인증 관련 API

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

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

결제 관련 API

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

결제 금액 사전 등록 관련 API

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

비인증 결제 관련 API

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

정기 결제 관련 API

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

빌링키 관련 API

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

가상계좌 관련 API

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

가상계좌 발급 API

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

지원되는 PG사

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

Request

Query

pg_api_key?: string

Api Key

(Optional)

이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값

Body

merchant_uid: string

고객사 주문번호

amount: number

입금 예정 금액

product_type?: string

상품구분

(Optional)

vbank_num?: string

고정 가상 계좌 번호

(Optional)

vbank_code: string

은행구분코드

가상계좌 발급을 위한 은행구분코드

vbank_due: integer

가상계좌 입금기한

vbank_holder?: string

가상계좌 예금주명

(Optional)

vbank_key?: string

계좌 고유 키

(Optional)

name?: string

주문명

(Optional)

buyer_name?: string

주문자명

(Optional)

buyer_email?: string

주문자 Email 주소

(Optional)

buyer_tel?: string

주문자 전화번호

(Optional)

business_registration_number?: string

사업자 등록번호

(Optional)

buyer_addr?: string

주문자 주소

(Optional)

buyer_postcode?: string

주문자 우편번호

(Optional)

pg?: string

PG사 구분코드

(Optional)

notice_url?: array

Notification URL(Webhook URL)

(Optional)

custom_data?: string

추가 정보

(Optional)

tax_free?: integer

면세금액

(Optional)

vat_amount?: number

부가세

(Optional)

product_count?: integer

결제 상품의 개수

(Optional)

Response

200

가상계좌 생성 완료

code?: integer

응답코드

(Optional)

message?: string

응답메세지

(Optional)

response?: PaymentAnnotation

(Optional)

imp_uid: string

포트원 거래고유번호

merchant_uid: string

고객사 주문번호

pay_method?: string

결제수단 구분코드

(Optional)

channel?: string

결제환경 구분코드

(Optional)

pg_provider?: string

PG사 구분코드

(Optional)

emb_pg_provider?: string

허브형결제 PG사 구분코드

(Optional)

pg_tid?: string

PG사 거래번호

(Optional)

pg_id?: string

PG사 상점아이디

(Optional)

escrow?: boolean

에스크로결제 여부

(Optional)

apply_num?: string

승인번호

(Optional)

bank_code?: string

은행 표준코드

(Optional)

bank_name?: string

은행명

(Optional)

card_code?: string

카드사 코드번호

(Optional)

card_name?: string

카드사명

(Optional)

card_issuer_code?: string

카드 발급사 코드

(Optional)

card_issuer_name?: string

카드 발급사명

(Optional)

card_publisher_code?: string

카드 발행사 코드

(Optional)

card_publisher_name?: string

카드 발행사명

(Optional)

card_quota?: integer

할부개월 수

(Optional)

card_number?: string

카드번호

(Optional)

결제에 사용된 마스킹된 카드번호

card_type?: integer

카드 구분코드

(Optional)

결제건에 사용된 카드 구분코드

vbank_code?: string

가상계좌 은행 표준코드

(Optional)

vbank_name?: string

가상계좌 은행명

(Optional)

vbank_num?: string

가상계좌 계좌번호

(Optional)

vbank_holder?: string

가상계좌 예금주

(Optional)

vbank_date?: integer

가상계좌 입금기한

(Optional)

vbank_issued_at?: integer

가상계좌 생성시각

(Optional)

name?: string

제품명

(Optional)

amount: number

결제금액

cancel_amount: number

취소금액

currency: string

결제통화 구분코드

buyer_name?: string

주문자명

(Optional)

buyer_email?: string

주문자 Email주소

(Optional)

buyer_tel?: string

주문자 전화번호

(Optional)

buyer_addr?: string

주문자 주소

(Optional)

buyer_postcode?: string

주문자 우편번호

(Optional)

custom_data?: string

추가정보

(Optional)

user_agent?: string

단말기의 UserAgent 문자열

(Optional)

status: string

결제상태

started_at?: integer

요청 시각

(Optional)

paid_at?: integer

결제 시각

(Optional)

결제건의 결제완료 시각 UNIX timestamp

failed_at?: integer

실패시각

(Optional)

결제건의 결제실패시각 UNIX timestamp

cancelled_at?: integer

취소시각

(Optional)

결제건의 결제취소시각 UNIX timestamp

fail_reason?: string

결제실패 사유

(Optional)

결제건의 결제실패 사유

cancel_reason?: string

결제취소 사유

(Optional)

결제건의 결제취소 사유

receipt_url?: string

매출전표 URL

(Optional)

cancel_history?: PaymentCancelAnnotation[]

취소 내역

(Optional)

cancel_receipt_urls?: string[]

(Optional)

(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨

cash_receipt_issued?: boolean

현금영수증 발급 여부

(Optional)

customer_uid?: string

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

(Optional)

customer_uid_usage?: string

구매자의 결제 수단 식별 고유번호 사용 구분코드

(Optional)

promotion?: object

프로모션 정보

(Optional)

401

인증 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

발급금액

(Optional)

vbank_due?: integer

입금기한

(Optional)

Response

200

가상계좌 수정 완료

code?: integer

응답코드

(Optional)

message?: string

응답메세지

(Optional)

response?: PaymentAnnotation

(Optional)

imp_uid: string

포트원 거래고유번호

merchant_uid: string

고객사 주문번호

pay_method?: string

결제수단 구분코드

(Optional)

channel?: string

결제환경 구분코드

(Optional)

pg_provider?: string

PG사 구분코드

(Optional)

emb_pg_provider?: string

허브형결제 PG사 구분코드

(Optional)

pg_tid?: string

PG사 거래번호

(Optional)

pg_id?: string

PG사 상점아이디

(Optional)

escrow?: boolean

에스크로결제 여부

(Optional)

apply_num?: string

승인번호

(Optional)

bank_code?: string

은행 표준코드

(Optional)

bank_name?: string

은행명

(Optional)

card_code?: string

카드사 코드번호

(Optional)

card_name?: string

카드사명

(Optional)

card_issuer_code?: string

카드 발급사 코드

(Optional)

card_issuer_name?: string

카드 발급사명

(Optional)

card_publisher_code?: string

카드 발행사 코드

(Optional)

card_publisher_name?: string

카드 발행사명

(Optional)

card_quota?: integer

할부개월 수

(Optional)

card_number?: string

카드번호

(Optional)

결제에 사용된 마스킹된 카드번호

card_type?: integer

카드 구분코드

(Optional)

결제건에 사용된 카드 구분코드

vbank_code?: string

가상계좌 은행 표준코드

(Optional)

vbank_name?: string

가상계좌 은행명

(Optional)

vbank_num?: string

가상계좌 계좌번호

(Optional)

vbank_holder?: string

가상계좌 예금주

(Optional)

vbank_date?: integer

가상계좌 입금기한

(Optional)

vbank_issued_at?: integer

가상계좌 생성시각

(Optional)

name?: string

제품명

(Optional)

amount: number

결제금액

cancel_amount: number

취소금액

currency: string

결제통화 구분코드

buyer_name?: string

주문자명

(Optional)

buyer_email?: string

주문자 Email주소

(Optional)

buyer_tel?: string

주문자 전화번호

(Optional)

buyer_addr?: string

주문자 주소

(Optional)

buyer_postcode?: string

주문자 우편번호

(Optional)

custom_data?: string

추가정보

(Optional)

user_agent?: string

단말기의 UserAgent 문자열

(Optional)

status: string

결제상태

started_at?: integer

요청 시각

(Optional)

paid_at?: integer

결제 시각

(Optional)

결제건의 결제완료 시각 UNIX timestamp

failed_at?: integer

실패시각

(Optional)

결제건의 결제실패시각 UNIX timestamp

cancelled_at?: integer

취소시각

(Optional)

결제건의 결제취소시각 UNIX timestamp

fail_reason?: string

결제실패 사유

(Optional)

결제건의 결제실패 사유

cancel_reason?: string

결제취소 사유

(Optional)

결제건의 결제취소 사유

receipt_url?: string

매출전표 URL

(Optional)

cancel_history?: PaymentCancelAnnotation[]

취소 내역

(Optional)

cancel_receipt_urls?: string[]

(Optional)

(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨

cash_receipt_issued?: boolean

현금영수증 발급 여부

(Optional)

customer_uid?: string

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

(Optional)

customer_uid_usage?: string

구매자의 결제 수단 식별 고유번호 사용 구분코드

(Optional)

promotion?: object

프로모션 정보

(Optional)

400

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

401

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

404

유효하지 않은 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

(Optional)

이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값

Response

200

가상계좌 말소 완료

code?: integer

응답코드

(Optional)

message?: string

응답메세지

(Optional)

response?: PaymentAnnotation

(Optional)

imp_uid: string

포트원 거래고유번호

merchant_uid: string

고객사 주문번호

pay_method?: string

결제수단 구분코드

(Optional)

channel?: string

결제환경 구분코드

(Optional)

pg_provider?: string

PG사 구분코드

(Optional)

emb_pg_provider?: string

허브형결제 PG사 구분코드

(Optional)

pg_tid?: string

PG사 거래번호

(Optional)

pg_id?: string

PG사 상점아이디

(Optional)

escrow?: boolean

에스크로결제 여부

(Optional)

apply_num?: string

승인번호

(Optional)

bank_code?: string

은행 표준코드

(Optional)

bank_name?: string

은행명

(Optional)

card_code?: string

카드사 코드번호

(Optional)

card_name?: string

카드사명

(Optional)

card_issuer_code?: string

카드 발급사 코드

(Optional)

card_issuer_name?: string

카드 발급사명

(Optional)

card_publisher_code?: string

카드 발행사 코드

(Optional)

card_publisher_name?: string

카드 발행사명

(Optional)

card_quota?: integer

할부개월 수

(Optional)

card_number?: string

카드번호

(Optional)

결제에 사용된 마스킹된 카드번호

card_type?: integer

카드 구분코드

(Optional)

결제건에 사용된 카드 구분코드

vbank_code?: string

가상계좌 은행 표준코드

(Optional)

vbank_name?: string

가상계좌 은행명

(Optional)

vbank_num?: string

가상계좌 계좌번호

(Optional)

vbank_holder?: string

가상계좌 예금주

(Optional)

vbank_date?: integer

가상계좌 입금기한

(Optional)

vbank_issued_at?: integer

가상계좌 생성시각

(Optional)

name?: string

제품명

(Optional)

amount: number

결제금액

cancel_amount: number

취소금액

currency: string

결제통화 구분코드

buyer_name?: string

주문자명

(Optional)

buyer_email?: string

주문자 Email주소

(Optional)

buyer_tel?: string

주문자 전화번호

(Optional)

buyer_addr?: string

주문자 주소

(Optional)

buyer_postcode?: string

주문자 우편번호

(Optional)

custom_data?: string

추가정보

(Optional)

user_agent?: string

단말기의 UserAgent 문자열

(Optional)

status: string

결제상태

started_at?: integer

요청 시각

(Optional)

paid_at?: integer

결제 시각

(Optional)

결제건의 결제완료 시각 UNIX timestamp

failed_at?: integer

실패시각

(Optional)

결제건의 결제실패시각 UNIX timestamp

cancelled_at?: integer

취소시각

(Optional)

결제건의 결제취소시각 UNIX timestamp

fail_reason?: string

결제실패 사유

(Optional)

결제건의 결제실패 사유

cancel_reason?: string

결제취소 사유

(Optional)

결제건의 결제취소 사유

receipt_url?: string

매출전표 URL

(Optional)

cancel_history?: PaymentCancelAnnotation[]

취소 내역

(Optional)

cancel_receipt_urls?: string[]

(Optional)

(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨

cash_receipt_issued?: boolean

현금영수증 발급 여부

(Optional)

customer_uid?: string

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

(Optional)

customer_uid_usage?: string

구매자의 결제 수단 식별 고유번호 사용 구분코드

(Optional)

promotion?: object

프로모션 정보

(Optional)

400

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

401

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

404

유효하지 않은 imp_uid

try

Request

Request Sample

N/A

get/vbanks/holder

예금주 조회 API

가상계좌 환불 전, 확인차원에서 예금주를 조회하는 API
은행코드, 계좌번호를 이용해 해당 계좌의 예금주 명을 조회합니다.

KB국민은행	004
SC제일은행	023
경남은행	039
광주은행	034
기업은행	003
농협	011
대구은행	031
부산은행	032
산업은행	002
수협	007
신한은행	088
신협	048
외환은행	005
우리은행	020
우체국	071
전북은행	037
제주은행	035
축협	012
하나은행(서울은행)	081
한국씨티은행(한미은행)	027
K뱅크	089
카카오뱅크	090
유안타증권	209
현대증권	218
미래에셋증권	230
대우증권	238
삼성증권	240
한국투자증권	243
우리투자증권	247
교보증권	261
하이투자증권	262
에이치엠씨투자증권	263
키움증권	264
이트레이드증권	265
에스케이증권	266
대신증권	267
솔로몬투자증권	268
한화증권	269
하나대투증권	270
굿모닝신한증권	278
동부증권	279
유진투자증권	280
메리츠증권	287
엔에이치투자증권	289
부국증권	290

Request

Query

bank_code: string

은행코드

bank_num: string

계좌번호

Response

200

예금주 조회 성공

code?: integer

응답코드

(Optional)

message?: string

응답메세지

(Optional)

response?: VbankHolderAnnotation

(Optional)

bank_holder: string

예금주명

400

bank_code가 누락된 경우/ bank_num이 누락된 경우

401

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

404

계좌정보 조회 실패

try

Request

Request Sample

N/A

PG사 관련 API

PG사 별 추가로 지원하는 기능을 제공합니다.

카카오 관련 API

카카오페이에서 지원하는 기능을 제공합니다.

KCP 퀵페이 관련 API

KCP 퀵페이에서 지원하는 기능을 제공합니다.

네이버페이 관련 API

네이버페이에서 지원하는 기능을 제공합니다.

페이코 관련 API

페이코에서 지원하는 기능을 제공합니다.

페이먼트월 관련 API

페이먼트월에서 지원하는 기능을 제공합니다.

본인인증 관련 API

본인인증 요청 및 결과 조회와 관련된 기능을 제공합니다.

현금영수증 관련 API

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

에스크로 관련 API

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

고객사 정보 관련 API

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

고객사의 하위 상점 관련 API

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

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

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

편의점 결제 관련 API

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

타입 정의

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

AuthAnnotation AuthResponse BenepiaPointAnnotation BenepiaPointResponse CertificationAnnotation CertificationOTPAnnotation CertificationOTPResponse CertificationResponse CustomerAnnotation CustomerResponse EscrowLogisAnnotation EscrowLogisInfoAnnotation EscrowLogisProductsAnnotation EscrowLogisReceiverAnnotation EscrowLogisResponse EscrowLogisSenderAnnotation ExternalReceiptAnnotation ExternalReceiptResponse KcpQuickMemberAnnotation KcpQuickMemberResponse MultipleCustomersResponse MultiplePaymentsResponse MultiplePgSettingResponse NaverAddress NaverCashAmountAnnotation NaverCashAmountResponse NaverOrderer NaverProductOrderAnnotation NaverProductOrderArrayResponse NaverProductOrderResponse NaverReviewAnnotation NaverReviewsResponse PagedPaymentAnnotation PartnerReceiptResponse PartnerReceiptResultAnnotation PartnerReceiptsAnnotation PaycoStatusAnnotation PaycoStatusResponse PaymentAnnotation PaymentBalanceAnnotation PaymentBalanceHistoriesAnnotation PaymentBalanceResponse PaymentBalanceResponseAnnotation PaymentCancelAnnotation PaymentListResponse PaymentPrepareAnnotation PaymentPrepareResponse PaymentResponse PaymentwallDeliveryAnnotation PaymentwallDeliveryDetailAnnotation PgSettingAnnotation ReceiptAnnotation ReceiptResponse ResponseAnnotation ScheduleAnnotation ScheduleResponse ScheduleResultAnnotation SingleScheduleResponse StandardCodeAnnotation StandardCodeListResponse StandardCodeResponse SubscribePaymentExtra TierAnnotation TierResponse VbankHolderAnnotation VbankHolderResponse

PortOne REST API - V1

인증 관련 API

목차

결제 관련 API

목차

결제 금액 사전 등록 관련 API

목차

비인증 결제 관련 API

목차

정기 결제 관련 API

목차

빌링키 관련 API

목차

가상계좌 관련 API

목차

가상계좌 발급 API

지원되는 PG사

Request

Query

Body

Response

200

401

가상계좌 발급정보 수정 API

Request

Path

Body

Response

200

400

401

404

가상계좌 발급취소 API

지원되는 PG사

Request

Path

Query

Response

200

400

401

404

예금주 조회 API

Request

Query

Response

200

400

401

404

PG사 관련 API

카카오 관련 API

KCP 퀵페이 관련 API

목차

네이버페이 관련 API

목차

페이코 관련 API

목차

페이먼트월 관련 API

목차

본인인증 관련 API

목차

현금영수증 관련 API

목차

에스크로 관련 API

목차

고객사 정보 관련 API

목차

고객사의 하위 상점 관련 API

목차

하위 상점 관련 API

목차

기타 API

베네피아 포인트 관련 API

목차

결제기관 관련 API

목차

편의점 결제 관련 API

목차

타입 정의