PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
2024년 9월 1일부로 포트원 V1 API에 대해 일부 보안 규격이 지원 종료됩니다.
자세한 사항은 TLS 지원 범위를 참고해주세요.
V1 API hostname: api.iamport.kr
하위호환성
포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.
-
현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
-
입력 형식 내 필드 정의가 삭제되지 않습니다.
-
필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
- 오로지 선택 입력 정보만 추가될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
enum 타입의 값이 삭제되지 않습니다.
-
-
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
-
출력 형식 내 필드 정의가 삭제되지 않습니다.
-
사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
- 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
- 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
-
하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
-
단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
- 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
-
UNSTABLE이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.
하위 상점의 API 사용
하위 상점에 대해 API를 사용하려는 경우 API 호출 시 Tier 헤더(HTTP Request Header)로 하위상점의 티어코드를 전달해야 합니다.
[Agency & Tier 란?]
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
결제 관련 API
목차
결제 금액 사전 등록 관련 API
비인증 결제 관련 API
정기 결제 관련 API
목차
빌링키 관련 API
목차
가상계좌 관련 API
PG사 관련 API
카카오 관련 API
KCP 퀵페이 관련 API
페이코 관련 API
페이먼트월 관련 API
본인인증 관련 API
본인인증 결과조회 API
Request
Path
본인인증 결과로 리턴 받은 포트원 인증 고유번호
Response
200 Ok
본인인증결과 조회 성공
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404 Error
본인인증결과를 찾을 수 없음
본인인증 정보삭제 API
본인인증 결과정보를 포트원 서버내에서 완전히 삭제하고 싶을 때 요청합니다.
Request
Path
본인인증 결과로 리턴받은 포트원 인증 고유번호
Response
200 Ok
본인인증결과 삭제 완료
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404 Error
본인인증결과를 찾을 수 없음
500 Error
DB삭제도중 서버 장애 발생
본인인증 요청 API
통신사 승인을 받은 일부 고객사에 한해 사용하실 수 있으며, 현재 다날, kcp(신모듈)을 통해서만 서비스되고 있습니다.
본인인증 대상자의 성명, 생년월일 + 주민등록 뒷부분 첫 자리, 휴대폰번호, 통신사 정보를 고객사에서 직접 입력받아 API요청하면 됩니다. 전달된 개인정보가 올바를 경우 해당 휴대폰으로 인증번호 SMS가 전송됩니다.
200응답 시 imp_uid 가 응답데이터로 전달되며, SMS전송된 인증번호를 본인인증 완료 API 로 요청주시면 최종 본인인증 프로세스가 완료됩니다.
Request
Body
본인인증 대상자 성명
- 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리
YYMMDD 6자리(연/월/일 사이에 - 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리함)
주민등록번호 13자리 중 7번째 자리
2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4 kcp(신모듈)의 경우 외국인 고객은 다음 기준에 따라 입력해주세요:
- 남성: ~1999년생은 5, 2000년 이후 출생자는 7
- 여성: ~1999년생은 6, 2000년 이후 출생자는 8
알뜰폰 사용자의 경우, carrier파라메터 SKT, KT, LGT 중 하나를 지정한 후 is_mvno : true 로 설정
- SKT
- KT
- LGT
본인인증 대상자 알뜰폰 사용 여부
KISA에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭
본인인증 요청건을 식별하기 위한 고객사 주문번호
다날 상점아이디를 2개 이상 동시에 사용하시려는 경우 설정하시면 됩니다. danal.{상점아이디} 형태로 지정. Deprecated 되었으므로 channelKey 파라미터를 사용해주세요.
kcp(신모듈) 본인인증을 사용하시려는 경우 반드시 channelKey를 입력해야합니다.
본인인증을 진행하고자 하는 방식. (현재 kcp(신모듈)만 지원)
- SMS
- APP
전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요
Response
200 Ok
본인인증을 위한 대상자 정보 검증 완료(인증번호 SMS전송요청 중)
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
400 Error
대상자 개인정보 중 일부가 누락되었거나 올바르지 않은 경우
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
500 Error
처리 중 다날서버 응답오류 등 오류가 발생한 경우
본인인증 완료 API
본인인증이 완료되면 대상자의 이름, 전화번호, 통신사, 성별, 외국인 여부, 생년월일, CI, DI 값을 응답받을 수 있습니다.
Request
Path
본인인증 요청 API 요청 후 응답된 인증 고유번호
Body
SMS로 전송된 본인인증 번호. KCP (신모듈) APP 방식의 경우에는 해당 값을 전달하지 않습니다.
Response
200 Ok
본인인증완료
0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
400 Error
인증번호를 누락하였거나 이미 인증처리가 완료된 건에 대해 재요청하는 경우
401 Error
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404 Error
imp_uid 에 해당되는 요청건이 없는 경우
500 Error
처리 중 다날서버 응답오류 등 오류가 발생한 경우