PortOne REST API - V1
결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.
자세한 사항은TLS 지원 범위를 참고해주세요.
V1 API hostname: api.iamport.kr
하위호환성
포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.
현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
- 입력 형식 내 필드 정의가 삭제되지 않습니다.
필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
- 오로지 선택 입력 정보만 추가될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
- enum 타입의 값이 삭제되지 않습니다.
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
- 출력 형식 내 필드 정의가 삭제되지 않습니다.
사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
- 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
- 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
- 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
- 새로운 필드 및 값이 추가되는 경우 사전 공지를 통해 안내드립니다.
UNSTABLE
이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.
인증 관련 API
포트원 API를 호출할 때는 액세스 토큰을 Authorization
헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.
액세스 토큰 발급 API를 호출하려면 API 키와 API 시크릿을 인자로 넣어주어야 합니다.
결제 관련 API
목차
결제 금액 사전 등록 관련 API
비인증 결제 관련 API
정기 결제 관련 API
목차
빌링키 관련 API
목차
가상계좌 관련 API
가상계좌 발급 API
희망하시는 은행, 예금주명으로 입금이 가능한 가상계좌를 생성할 수 있습니다.(별도로 PG계약 필요)
은행구분코드는 페이지 가장 하단에 있는 은행코드표를 참조하시기 바랍니다.
지원되는 PG사
- 헥토파이낸셜(구 세틀뱅크)
- 나이스페이먼츠
- KG이니시스
- 토스페이먼츠 - 신모듈
- KSNET
- 스마트로 - 신모듈
- (신) 나이스페이
- 웰컴페이먼츠
Request
Query
이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값
Body
가상계좌 발급을 위한 은행구분코드
Response
200
가상계좌 생성 완료
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
가상계좌 발급정보 수정 API
아직 입금이 되지 않은 가상계좌의 입금기한 또는 입금금액을 수정할 수 있습니다. (헥토파이낸셜(구 세틀뱅크)만 사용 가능)
imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 수정이 가능합니다)
Request
Path
Body
Response
200
가상계좌 수정 완료
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
400
imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우/ 가상계좌가 입금대기 상태(ready)가 아닌 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
유효하지 않은 imp_uid
가상계좌 발급취소 API
아직 입금이 되지 않은 가상계좌를 말소시킴으로써 구매자가 실수로 입금하는 경우를 방지하도록 합니다.
imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 말소가 가능합니다)
지원되는 PG사
- KG이니시스
- NHN KCP
- 토스페이먼츠 - 구모듈
- 다날
- 나이스페이먼츠
- KICC
- 헥토파이낸셜(구 세틀뱅크)
- 스마트로 - 구모듈
- 토스페이먼츠 - 신모듈
- KSNET
- 스마트로 - 신모듈
- (신) 나이스페이
- 웰컴페이먼츠
Request
Path
Query
이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값
Response
200
가상계좌 말소 완료
결제에 사용된 마스킹된 카드번호
결제건에 사용된 카드 구분코드
결제건의 결제완료 시각 UNIX timestamp
결제건의 결제실패시각 UNIX timestamp
결제건의 결제취소시각 UNIX timestamp
결제건의 결제실패 사유
결제건의 결제취소 사유
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
400
imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우 / 가상계좌가 입금대기 상태(ready)가 아닌 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
유효하지 않은 imp_uid
예금주 조회 API
은행코드, 계좌번호를 이용해 해당 계좌의 예금주 명을 조회합니다.
KB국민은행 | 004 |
SC제일은행 | 023 |
경남은행 | 039 |
광주은행 | 034 |
기업은행 | 003 |
농협 | 011 |
대구은행 | 031 |
부산은행 | 032 |
산업은행 | 002 |
수협 | 007 |
신한은행 | 088 |
신협 | 048 |
외환은행 | 005 |
우리은행 | 020 |
우체국 | 071 |
전북은행 | 037 |
제주은행 | 035 |
축협 | 012 |
하나은행(서울은행) | 081 |
한국씨티은행(한미은행) | 027 |
K뱅크 | 089 |
카카오뱅크 | 090 |
유안타증권 | 209 |
현대증권 | 218 |
미래에셋증권 | 230 |
대우증권 | 238 |
삼성증권 | 240 |
한국투자증권 | 243 |
우리투자증권 | 247 |
교보증권 | 261 |
하이투자증권 | 262 |
에이치엠씨투자증권 | 263 |
키움증권 | 264 |
이트레이드증권 | 265 |
에스케이증권 | 266 |
대신증권 | 267 |
솔로몬투자증권 | 268 |
한화증권 | 269 |
하나대투증권 | 270 |
굿모닝신한증권 | 278 |
동부증권 | 279 |
유진투자증권 | 280 |
메리츠증권 | 287 |
엔에이치투자증권 | 289 |
부국증권 | 290 |
Request
Query
Response
200
예금주 조회 성공
400
bank_code가 누락된 경우/ bank_num이 누락된 경우
401
인증 Token이 전달되지 않았거나 유효하지 않은 경우
404
계좌정보 조회 실패