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
목차
빌링키 관련 API
목차
가상계좌 관련 API
PG사 관련 API
카카오 관련 API
KCP 퀵페이 관련 API
페이코 관련 API
페이먼트월 관련 API
본인인증 관련 API
현금영수증 관련 API
에스크로 관련 API
가맹점 정보 관련 API
가맹점의 하위가맹점 관련 API
하위 상점 관련 API
기타 API
베네피아 포인트 관련 API
결제기관 관련 API
편의점 결제 관련 API
수납번호 발급 API
Request
Body
이미 결제가 이뤄진 적이 있는 merchant_uid로는 추가적인 편의점결제 수납번호(barcode) 발급 또는 등록이 불가능합니다.
결제하고자 하는 금액
가맹점에서 직접 생성, 관리하는 바코드(barcode)번호가 있는 경우, 갤럭시아컴즈로부터 신규 수납번호(barcode)를 발급요청하지 않고 가맹점에서 관리하는 바코드(barcode)번호를 등록하여 수납번호로 활용할 수 있습니다.
편의점 수납가능한 결제기한(Unix Timestamp). 정의하지 않으면 갤럭시아컴즈와 계약시 협의한 기본값이 적용됩니다.
주문명
주문자의 이름
주문자 Email 주소
주문자 전화번호
주문자의 주소
주문자의 우편번호
결제 하고자 하는 PG사 구분코드
고객이 편의점결제 수납시도 시 수납가능여부를 체크하기 위한 URL
편의점결제 수납성공 시 통지받을 URL
결제정보와 함께 저장할 custom_data. 객체로 전달되는 경우 JSON 문자열로 저장
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
Path
편의점결제 수납번호(barcode) 발급/등록된 포트원 거래고유번호
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사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.
결제건의 취소/부분취소 내역
결제건의 현금영수증 발급 여부
결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드