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
비인증 결제 관련 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. JTNet, 이니시스-빌링)
- 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. JTNet, 이니시스-빌링)
- 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사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.
결제건의 취소/부분취소 내역
결제건의 현금영수증 발급 여부
결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드