PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
V1 API hostname: api.iamport.kr
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization
헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
결제 관련 API
목차
결제 금액 사전 등록 관련 API
비인증 결제 관련 API
비 인증 결제(일회성) API
빌링키 저장 시, buyer_email, buyer_name 등의 정보는 customer 부가정보인 customer_email, customer_name 등으로 함께 저장됩니다.
빌링키 발급 API참조
Request
Body
고객사 거래 고유번호로 매 결제요청 시 고유값으로 요청해야 합니다.
통화 e.g.) KRW, USD, VND, ... Default: KRW
결제요청 할 금액
amount 중 면세공급가액
부가세를 지정할 수 있으며, tax_free=0, vat_amount=0
으로 영세율로 결제 가능합니다.
PG사와의 사전 협의 후 사용가능합니다. (기본값: null)
결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)
카드번호(dddd-dddd-dddd-dddd
) 기재 양식을 유의하세요.
카드 유효기간(YYYY-MM
) 기재 양식을 유의하세요.
PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.
생년월일 기재가 필요없는 해외 PG사 결제 요청의 경우 000000
으로 고정 기재하도 무방합니다.
PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.
결제 요청할 카드의 인증번호 (카드 뒷면 3자리, AMEX의 경우 4자리)
빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제 요청할 PG사 구분코드
결제요청 할 결제건의 주문명
결제건의 구매자명
결제건의 주문자 E-mail주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제금액 50,000원 이상 한정으로 2 이상의 integer 할부개월수가 적용가능합니다.
카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (PG사와 사전 계약이 필요)
승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. PG사 영업담당자와 계약 당시 사전 협의 필요
거래정보와 함께 저장할 추가 정보
결제성공 시 통지될 Notification URL(Webhook URL)
구매자 브라우져(PC)의 IP
해외PG 전용 파라미터로 3D secure 인증 후 재결제시 PG사에서 부여한 결제 ID
해외PG 전용 파라미터로 3D secure 인증 후 재결제시 PG사에서 부여한 토큰
결제 요청할 판매 상품에 대한 구분 값
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
결제건의 포트원 거래고유번호
결제건의 고객사 주문번호
결제건의 결제수단을 구분하는 코드
결제건을 생성한 환경을 구분하는 코드
결제건의 PG사 구분코드
허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드
결제건의 PG사 거래번호
결제건의 PG사 상점아이디
에스크로 결제건인지 구분하는 코드
결제건의 신용카드 승인번호
결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우
결제건의 은행명 - 실시간계좌이체 결제 건의 경우
결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우
결제건의 카드사명 - 카드 결제 건의 경우
결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
결제한 카드의 발급사명 - 카드 결제 건의 경우
발급사 코드를 지원하는 pg사에 한해 제공됩니다.
결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
결제 한 카드의 발행사명 - (카드 결제 건의 경우)
발행사 코드를 지원하는 pg사에 한해 제공됩니다.
결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우
7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우
결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우
결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우
결제건의 제품명
결제건의 결제금액
결제건의 누적 취소금액
외환분호 e.g) KRW, USD, VND, ... Default: KRW
결제건의 주문자명
결제건의 주문자의 Email주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제 요청시 고객사에서 전달한 추가정보 (JSON string으로 전달)
구매자가 결제시 사용한 단말기의 UserAgent 문자열
결제건의 결제상태
결제건의 결제요청 시각 UNIX timestamp
결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.
결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.
결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.
결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.
결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.
결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.
결제건의 취소/부분취소 내역
결제건의 현금영수증 발급 여부
결제건에 사용된 빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드
401
비 인증 결제(빌링키) API
Request
Body
빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제 요청할 결제건의 고객사 거래 고유번호
통화 e.g.) KRW, USD, VND, ... Default: KRW
결제 요청할 금액
amount 중 면세공급가액
부가세를 지정할 수 있으며, tax_free=0, vat_amount=0
으로 영세율로 결제 가능합니다.(기본값: null)
결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)
결제 요청할 결제건의 제품명
결제건의 주문자명
결제건의 주문자 E-mail주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제건의 카드 할부 개월 수로 기본값은 **0(일시불)**입니다.
카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (PG사와 사전 계약이 필요)
승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. PG사 영업담당자와 계약 당시 사전 협의 필요
거래정보와 함께 저장할 추가 정보
결제성공 시 통지될 Notification URL(Webhook URL)
구매자 브라우져(PC)의 IP
결제 요청할 판매 상품에 대한 구분 값
결제 상품의 개수로 기본값은 1입니다.
현금영수증 발행대상의 구분 값
전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요
비인증 결제 요청 시 추가 파라미터
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
결제건의 포트원 거래고유번호
결제건의 고객사 주문번호
결제건의 결제수단을 구분하는 코드
결제건을 생성한 환경을 구분하는 코드
결제건의 PG사 구분코드
허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드
결제건의 PG사 거래번호
결제건의 PG사 상점아이디
에스크로 결제건인지 구분하는 코드
결제건의 신용카드 승인번호
결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우
결제건의 은행명 - 실시간계좌이체 결제 건의 경우
결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우
결제건의 카드사명 - 카드 결제 건의 경우
결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
결제한 카드의 발급사명 - 카드 결제 건의 경우
발급사 코드를 지원하는 pg사에 한해 제공됩니다.
결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
결제 한 카드의 발행사명 - (카드 결제 건의 경우)
발행사 코드를 지원하는 pg사에 한해 제공됩니다.
결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우
7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우
결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우
결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우
결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우
결제건의 제품명
결제건의 결제금액
결제건의 누적 취소금액
외환분호 e.g) KRW, USD, VND, ... Default: KRW
결제건의 주문자명
결제건의 주문자의 Email주소
결제건의 주문자 전화번호
결제건의 주문자 주소
결제건의 주문자 우편번호
결제 요청시 고객사에서 전달한 추가정보 (JSON string으로 전달)
구매자가 결제시 사용한 단말기의 UserAgent 문자열
결제건의 결제상태
결제건의 결제요청 시각 UNIX timestamp
결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.
결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.
결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.
결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.
결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.
결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.
결제건의 취소/부분취소 내역
결제건의 현금영수증 발급 여부
결제건에 사용된 빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드