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
등록된 카드마다 1개의 customer_uid가 매핑되므로, 가맹점 시스템 내에 1명의 고객이 여러 장의 카드를 등록할 수 있는 경우 여러 개의 customer_uid를 가지게 됩니다.
해당 고객이 등록해놓은 카드정보 목록을 한 번에 조회하는데 사용하면 편리합니다.
예시) /subscribe/customers?customer_uid[]=hong_1234_a&customer_uid[]=hong_1234_b
Request
Query
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
빌링키가 등록된 PG사 구분코드
빌링키가 등록된 PG사 상점아이디(MID)
구매자 식별 고유 번호
빌링키 발급 한 카드명
카드 발급사 코드번호 (금융결제원 표준코드 번호)
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발급사명
발급사 코드를 지원하는 pg사에 한해 제공됩니다.카드 발행사 코드번호 (금융결제원 표준코드 번호)
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발행사명
발행사 코드를 지원하는 pg사에 한해 제공됩니다.빌링키 발급 한 카드의 마스킹된 카드번호
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됩니다.(ex. JTNet, 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
빌링키 발급 한 고객(카드소지자)의 성함
빌링키 발급 한 고객(카드소지자)의 전화번호
빌링키 발급 한 고객(카드소지자)의 Email 주소
빌링키 발급 한 고객(카드소지자)의 주소
빌링키 발급 한 고객(카드소지자)의 우편번호
빌링키가 발급된 시각 UNIX timestamp
빌링키가 업데이트된 시각 UNIX timestamp
207
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
빌링키가 등록된 PG사 구분코드
빌링키가 등록된 PG사 상점아이디(MID)
구매자 식별 고유 번호
빌링키 발급 한 카드명
카드 발급사 코드번호 (금융결제원 표준코드 번호)
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발급사명
발급사 코드를 지원하는 pg사에 한해 제공됩니다.카드 발행사 코드번호 (금융결제원 표준코드 번호)
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발행사명
발행사 코드를 지원하는 pg사에 한해 제공됩니다.빌링키 발급 한 카드의 마스킹된 카드번호
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됩니다.(ex. JTNet, 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
빌링키 발급 한 고객(카드소지자)의 성함
빌링키 발급 한 고객(카드소지자)의 전화번호
빌링키 발급 한 고객(카드소지자)의 Email 주소
빌링키 발급 한 고객(카드소지자)의 주소
빌링키 발급 한 고객(카드소지자)의 우편번호
빌링키가 발급된 시각 UNIX timestamp
빌링키가 업데이트된 시각 UNIX timestamp
401
404
빌링키 정보 단건조회 API
Request
Path
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
빌링키가 등록된 PG사 구분코드
빌링키가 등록된 PG사 상점아이디(MID)
구매자 식별 고유 번호
빌링키 발급 한 카드명
카드 발급사 코드번호 (금융결제원 표준코드 번호)
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발급사명
발급사 코드를 지원하는 pg사에 한해 제공됩니다.카드 발행사 코드번호 (금융결제원 표준코드 번호)
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발행사명
발행사 코드를 지원하는 pg사에 한해 제공됩니다.빌링키 발급 한 카드의 마스킹된 카드번호
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됩니다.(ex. JTNet, 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
빌링키 발급 한 고객(카드소지자)의 성함
빌링키 발급 한 고객(카드소지자)의 전화번호
빌링키 발급 한 고객(카드소지자)의 Email 주소
빌링키 발급 한 고객(카드소지자)의 주소
빌링키 발급 한 고객(카드소지자)의 우편번호
빌링키가 발급된 시각 UNIX timestamp
빌링키가 업데이트된 시각 UNIX timestamp
401
404
빌링키 발급 API
해당 빌링키 발급 API는 PG사와 협의가 완료된 경우 이용 가능한 서비스입니다.
- PG사 협의를 통해 카드정보 필수 조건 값 조정이 가능합니다.
- 민감한 카드정보를 이용하기 때문에 보안에 특히 유의하셔야 합니다.
- customer_uid 값은 고객 & 카드번호 단위별로 고유하게 발급 관리되어야 합니다
Request
Path
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
Body
빌링키 발급을 받고자 하는 PG사 구분코드
구매자 식별 고유 번호
빌링키 발급 하고자 하는 카드의 번호(dddd-dddd-dddd-dddd)
빌링키 발급 하고자 하는 카드 유효기간(YYYY-MM)
법인카드의 경우 사업자등록번호10자리
PG사별로 혹은 계약상황에따라 필수값 여부가 상이합니다.
PG사별 혹은 계약상황에 따라 필수값 여부가 상이합니다.
빌링키 발급 받고자 하는 카드 카드 뒷면 3자리, AMEX의 경우 4자리
고객(카드소지자) 관리용 성함
고객(카드소지자) 전화번호
고객(카드소지자) Email
고객(카드소지자) 주소
고객(카드소지자) 우편번호
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
빌링키가 등록된 PG사 구분코드
빌링키가 등록된 PG사 상점아이디(MID)
구매자 식별 고유 번호
빌링키 발급 한 카드명
카드 발급사 코드번호 (금융결제원 표준코드 번호)
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발급사명
발급사 코드를 지원하는 pg사에 한해 제공됩니다.카드 발행사 코드번호 (금융결제원 표준코드 번호)
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발행사명
발행사 코드를 지원하는 pg사에 한해 제공됩니다.빌링키 발급 한 카드의 마스킹된 카드번호
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됩니다.(ex. JTNet, 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
빌링키 발급 한 고객(카드소지자)의 성함
빌링키 발급 한 고객(카드소지자)의 전화번호
빌링키 발급 한 고객(카드소지자)의 Email 주소
빌링키 발급 한 고객(카드소지자)의 주소
빌링키 발급 한 고객(카드소지자)의 우편번호
빌링키가 발급된 시각 UNIX timestamp
빌링키가 업데이트된 시각 UNIX timestamp
401
빌링키 삭제 API
빌링키 삭제시 결제예약된 내역이 존재하는지 반드시 확인하셔야 합니다.
삭제된 빌링키는 복구할 수 없습니다.
Request
Path
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
Query
빌링키를 삭제하려는 사유
빌링키 삭제 요청자
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
빌링키가 등록된 PG사 구분코드
빌링키가 등록된 PG사 상점아이디(MID)
구매자 식별 고유 번호
빌링키 발급 한 카드명
카드 발급사 코드번호 (금융결제원 표준코드 번호)
발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발급사명
발급사 코드를 지원하는 pg사에 한해 제공됩니다.카드 발행사 코드번호 (금융결제원 표준코드 번호)
발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- (신) 토스페이빌링키 발급 한 카드의 발행사명
발행사 코드를 지원하는 pg사에 한해 제공됩니다.빌링키 발급 한 카드의 마스킹된 카드번호
주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됩니다.(ex. JTNet, 이니시스-빌링)
- 0 : 신용카드
- 1 : 체크카드
빌링키 발급 한 고객(카드소지자)의 성함
빌링키 발급 한 고객(카드소지자)의 전화번호
빌링키 발급 한 고객(카드소지자)의 Email 주소
빌링키 발급 한 고객(카드소지자)의 주소
빌링키 발급 한 고객(카드소지자)의 우편번호
빌링키가 발급된 시각 UNIX timestamp
빌링키가 업데이트된 시각 UNIX timestamp
401
404
빌링키 결제 복수조회 API (빌링키 결제 내역 확인)
Request
Path
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
Query
조회목록 페이징으로 기본값은 1입니다.
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
조회한 결제 상태에 대한 전체 건수
이전 page숫자로 이전 페이지가 없는 경우 0을 반환합니다.
다음 page숫자로 다음 페이지가 없는 경우 0을 반환합니다.
결제 상세정보 배열로 최대 20개를 반환합니다. 바로 아래 Payment structure를 확인해주세요.
401
404
빌링키 결제예약 조회 API
customer_uid별 결제예약목록을 조회할 수 있습니다. 결제예약정보가 (페이징된)목록으로 전달되며, 최대 3개월 단위로 조회가 가능합니다.
결제예약정보가 예약된 시각 기준으로 최신순으로 정렬되어 전달됩니다.
Request
Path
결제예약에 사용된 구매자의 결제 수단 식별 고유번호
Query
조회목록 페이징으로 기본값은 1입니다.
unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. from <= '예약시각')
unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. '예약시각' < to)
조회 하고자 하는 예약 상태
Response
200
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호
예약 결제건의 가맹점 주문번호
예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.
string 타입의 구매자 식별 고유번호
결제 예약시 요청한 결제 예정 시각 UNIX timestamp
실제 결제가 실행된 시각 UNIX timestamp
예약 결제 실행을 철회한 시각 UNIX timestamp
결제 예약시 요청한 결제금액
통화 e.g.) KRW, USD, VND, ... Default: KRW
예약 결제건의 제품명
예약 결제건의 주문자명
예약 결제건의 주문자 Email주소
예약 결제건의 주문자 전화번호
예약 결제건의 주문자 주소
예약 결제건의 주문자 우편번호
예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보
결제건의 예약상태
예약 결제건의 승인 상태
예약 결제건이 결제 승인에 실패한 경우, 실패사유