비대면 계좌개설 API신청 프로세스

개요

  1. 1. 우선 비대면계좌개설 신청 페이지로 접속하기 위해 비대면계좌개설_인가코드요청 API(/oauth2/code-newaccount)를 호출합니다.
  2. 2. 호출 결과 Response Header - location의 url값을 redirect하여 웹뷰에서 계좌개설 및 API신청을 진행합니다.
  3. 3. 웹뷰에서 계좌개설이 정상적으로 완료되었을 경우 등록된 Redirect URI로 인가코드(authorization_code)와 고객식별키(personalseckey)가 전송됩니다.
  4. 4. 이 두 가지를 사용해서 접근토큰발급 API(/oauth2/tokenP)를 호출하여 접근토큰(access_token), 갱신토큰(refresh_token)을 발급받으실 수 있습니다.

비대면계좌개설_인가코드요청_접근토큰발급

  • 운영 : https://openapi.koreainvestment.com:9443
  • 개발 : http://210.107.75.78:9443
  • 개발(웹소켓) : ws://210.107.75.79:21000
  • 가급적 개발 서버로 셋팅을 완료하고 운영으로 오픈하는 것을 권장드립니다.

비대면계좌개설_인가코드요청 API

POST /oauth2/code-newaccount

Request Body

Request Body 목록 Name, Type, Description 정보
Name Type Description
appkey 필수입력
String 제휴사의 앱키

제휴 등록 후 발급받은 제휴사의 앱키
redirect_uri 필수입력
String 리다이렉션 URI

제휴 등록 시 제출한 리다이렉션 URI
response_type 필수입력
String 응답구분

"code" : Authorazation 방식
corpno 필수입력
String 제휴사번호

제휴 등록된 제휴사 고유번호 5자리
partner_user 필수입력
String 고객ID

제휴사가 관리하는 고객ID
personalname 필수입력
String 고객명

제휴사가 관리하는 고객이름
roption 필수입력
String Return옵션

"P" : JSON
corp_name 필수입력
String 제휴사명

약관에 들어갈 제휴사명


※ corp_name 에 한글이 포함된 경우 UriEncoding(UTF-8)으로 세팅한 후 입력
state 필수입력
String 정해진 형식 없이, 인증 과정 중 동일한 값을 유지하여 CSRF 보안위협에 대응하기 위해 임의 설정 하는 값

(일반적으로 서비스 서버 및 앱 간 세션값으로 설정)
prdt_type_cd 필수입력
String 상품유형

01(주식) 22(연금저축) 03(국내파생) 08(해외파생)
overseas_yn 필수입력
String 상품유형해외주식신청여부

(1=신청 0=미신청)

(상품유형=01만 해외주식신청 가능)
ministock_yn 필수입력
String 미니스탁신청해외주식신청여부

(1=신청 0=미신청)

(미니스탁신청시 상품유형=01, 해외주식신청=1 이어야함)
api_yn 필수입력
String API신청

1=신청 0=미신청
ad_dis_prdt_cd 필수입력
String 자문일임상품코드

당사에서 부여한 자문일임코드(6자리)
personalphone 필수입력
String 휴대폰번호
ivac_id 필수입력
String 자문일임상품회원ID

제휴사에서 부여한 자문일임회원ID(16자리), 당사와 자문제휴인 경우 필수

※ IVAC_ID 생성규칙

. 앞 2자리는 자문사명의 영문초성, 뒤 14자리는 숫자

. 뒤 14자리는 숫자는자문사에서 규칙을 정하여 고객들의 IVAC_ID가 중복되지 않도록 발급

ex. AB20240613000001
contract_type 필수입력
String 계약종류

"0":일임계약

"1":자문계약

200:OK

{
    // Response
}

Response Body/Header (비대면계좌개설_인가코드요청)

Response Body

아래는 인가코드요청 API 정상 호출 시 받으실 수 있는 Response Body입니다.

세션키(session_key)의 유효시간은 1시간입니다. 1시간 내 인가코드 요청을 마쳐주세요.

Response Body목록 Name, Type, Description 정보
Name Type Description
session_key_expired long session key 유효 시간

EX) 1554611873
session_key String session key (유효시간 1시간)

EX) "1234567f-12f5-123d-a12f1-4b12345bb123"
cache_type String cache_type

EX) "session"
client_id String client id

EX) "BS123nAB7Pkdl6EYvkKuSma9PFjLyK88ZoJ"

Response Header

아래는 Response Header입니다. Header에 있는 location의 url값을 redirect하여 계속해서 인증을 진행하실 수 있습니다.

Response Header 목록 Name, Type, Description 정보
Name Type Description
Date String EX) Fri, 14 Oct 2022 00:44:33 GMT
X-Content-Type-Options String EX) nosniff
Location String Redirect URL 값

EX)https://210.107.75.95/mobile/nfaccount/nfaccount.jsp?cmd=MNF01010&response_type=code&...
Content-Length String EX) 161
X-ORACLE-DMS-ECID String EX) 001uaBhvabcK0kkkR06zzEiXqE0jYYz10007y1
X-ORACLE-DMS-RID String EX) 0:1
X-XSS-Protection String EX) 1; mode=block
Keep-Alive String EX) timeout=5, max=100
Connection String EX) Keep-Alive
Content-Type String EX) application/json

Redirect URL

URL값에는 아래와 같은 인자들이 포함되어 있습니다. 예시 URL 값은 다음과 같습니다.

# 예시 URL

https://210.107.75.95/mobile/nfaccount/nfaccount.jsp?cmd=MNF01010&response_type=code&appkey=...
Redirect URL 목록 Name, Type, Len, Description 정보
Name Type Len Description
response_type String 10 "Code" : Authorazation_code 방식

EX) "code"
appkey String 36 포탈에서 발급된 고객의 APPKey

EX)"ABC5pFKriXyXaKLavYaBCu9KDLSkdlskjfkj..."
redirect_uri String 500 포탈에서 등록된 고객의 Redirect URI

EX)https://openapi.koreainvstment.com:8090/api
session_key String 26 G/W 에서 발급하는 UUID 를 세션키로 사용

EX)"1234567f-12f5-123d-a12f1-4b12345bb123"
corpno String 5 제휴사번호

EX)"12345"
partner_user String 256 제휴사회원번호

EX)"pUser01"
personalname String 고객명

EX)"홍길동"
personalphone String 256 휴대폰번호

EX)"01000000000"
roption String 1 요청 Option

P - post(json body방식)

EX)"P"
corp_name String 60 제휴사명

EX)"한국투자증권"
prdt_type_cd String 2 상품유형

01(주식) 22(연금저축) 03(국내파생) 08(해외파생)

EX) "01"
overseas_yn String 1 해외주식신청여부(1=신청 0=미신청)

EX) "1" or "0"
ministock_yn String 1 미니스탁신청여부(1=신청 0=미신청)

EX) "1" or "0"
api_yn String 1 API신청여부(1=신청 0=미신청)

EX) "1" or "0"
ad_dis_prdt_cd String 6 당사에서 부여한 자문일임코드(6자리)

EX) "123123"
ivac_id String 16 제휴사에서 부여한 자문일임회원ID(16자리), 당사와 자문제휴인 경우 필수

EX) "AB20220908000021"
mini_yn String 1 미니스탁계좌여부(Y=신청 N=미신청)

EX) "Y" or "N" or null
isa_yn String 1 ISA계좌여부(Y=신청 N=미신청)

EX) "Y" or "N" or null
reregist_yn String 1 계좌지정여부

EX) "Y" or null
acctno String 10 계좌지정계좌번호(10자리)
EX) "1234567801" or null
thco_ivst_etrs_bzep_cd String 6 당사 투자자문사상품코드(6자리)
EX) "000123" or null

Header에 있는 location의 url값을 redirect하시면 웹뷰에아래와 같은 화면이 나타나 계속해서 인증을 진행하실 수 있습니다.

제휴사명(corp_name), cust_name(고객명) 인자에 한글이 포함된 경우 문자열이 깨질 수 있습니다. 해당 경우 encodeURIComponent 등의 메소드를 사용하여 UriEncoding(UTF-8)으로 세팅한 후 전달해주시면 됩니다.

비대면 계좌개설 및 API 신청 프로세스

웹뷰에서는 다음의 순서대로 비대면 계좌개설 및 API 신청이 이루어집니다

Open API 비대면 계좌개설 및 API신청 프로세스 예시 이미지
reirect 시 웹뷰에 뜨는 비대면 계좌개설 프로세스 예시 이미지
  1. 1. 비대면계좌개설 신청을 합니다.
  2. 2. 통신사 본인인증을 합니다.
  3. 3. 계좌개설 약관동의를 합니다.
  4. 4. 비대면 투자일임(자문)계약 등록 동의를 합니다.
  5. 5. (선택) 미니스탁 서비스 신청을 합니다. ministock_yn: Y인 경우에만 진행됩니다.
  6. 6. (선택) API 이용 신청을 합니다. api_yn: Y인 경우에만 진행됩니다.
  7. 7. 신분증 촬용 및 보유계좌를 인증합니다.
  8. 8. 본인확인사항을 입력합니다.(EDD 등)
  9. 9. 주소/연락처/통보지를 입력합니다.
  10. 10. 투자자정보확인서를 등록합니다.
  11. 11. 계좌비밀번호를 등록합니다.
  12. 12. 원장에서는 신규계좌번호를 채번한 뒤, 해외주식/해외ETF/미니스탁(선택)/API(선택)신청을 한 뒤 계좌개설이 완료됩니다.
  13. 13. 웹뷰에서는 원장의 12. 처리 중에 서비스 신청 중 안내가 띄워집니다. 이후 원장처리가 완료되면 종료 웹뷰가 띄워집니다.
  14. 14. 13번까지 완료되면, 등록된 제휴사 Redirect URI로 인가코드가 전달됩니다.

계좌개설 오류 안내 웹뷰

계좌개설단계 중 아래 5가지의 오류항목에 대해서, 오류안내 웹뷰를 제공하고 있으니 참고 부탁드립니다.

  1. 1. 비대면계좌개설(/oauth2/code-newaccount) API 호출 시 필수항목 누락
  2. 2. 미니스탁 중복 신청 (미니스탁 주민번호단위 1인 1계좌 가능)
  3. 3. 계좌개설 상품유형 오류 (01,22번 이외의 상품유형 호출 불가)
  4. 4. 01번 계좌개설시 해외주식 미신청 + 미니스탁 신청시 (미니스탁 신청시 해외주식 신청 필수)
  5. 5. 22번 계좌개설시 해외주식, 미니스탁 신청시 (연금저축계좌(22)는 신청 불가)
계좌개설 오류 안내 웹뷰 예시 예시 이미지

계좌개설 종료단계 가이드

계좌개설 종료단계 가이드 예시 이미지

Response Body (계좌개설완료)

계좌개설/API신청 정상 여부에 따른 Redirect_URL 응답 값 예시 이미지

계좌개설/API신청 정상 여부에 따른 Redirect_URL 응답 값 예시 이미지

위 표의 첫번째 항목인, API신청 및 계좌개설이 정상적으로 완료되었을 경우 Redirect URL에서 확인 가능한 Response Body는 아래와 같습니다.

인증 완료 후 redirect uri 에서 받은 body 값들은 인코딩되어 있습니다. 따라서 decodeURIComponent, json 등의 메소드를 사용하여 디코딩해서 사용하셔야 합니다.

인가코드(authorization_code)의 유효시간은 5분입니다. 5분 내 접근토큰 발급을 마쳐주세요.

인증 완료 후 redirect uri 에서 받은 body 값들은 UriEncoding(UTF-8) 되어 있습니다. 따라서 decodeURIComponent, json 등의 메소드를 사용하여 디코딩해서 사용하셔야 합니다.

Request Body (* 필수입력값) 목록 Name, Type, Description 정보
Name Type Description
acnt_dv String 계좌구분(01 : 신규계좌, 02:기존계좌)

EX) "01"
authorization_code String 인가코드(유효시간 5분)

EX) "b8eab638-775a-4d6f-b56c-bebaa882c266"
personalseckey String 고객식별키

EX) "cad38v5aa4d6fbzccd6czbebaa8….............."
bankcode String 은행코드

EX) "00010"
virtualacctno String 외화가상계좌번호

EX) "001231108721"
acctno String 계좌번호
EX) "12345678"
acct_prdt_cd String 미사용(null 값 회신됨
corpno String 제휴사번호

EX)"12345"
partner_user String 제휴사회원번호

제휴사가 관리하는 회원ID = 자문일임계약ID

EX) "AA1234567890123"
cust_name String 고객명

EX) "%EB%B0%95..."
UriEncoding(UTF-8) 된 상태
overseas_yn String 해외주식신청

1=신청 0=미신청 (상품유형=01만 해외주식신청 가능)

EX) "1" or "0"
ministock_yn String 미니스탁신청

1=신청 0=미신청 (미니스탁신청시 상품유형=01, 해외주식신청=1 이어야함)

EX) "1" or "0"
api_yn String API신청

1=신청 0=미신청

EX) "1" or "0"
state String 정해진 형식 없이, 인증 과정 중 동일한 값을 유지하여 CSRF 보안위협에 대응하기 위해 임의 설정 하는 값

(일반적으로 서비스 서버 및 앱 간 세션값으로 설정)
pns_sav_paylimt String 연금저축납입한도

연간납입한도금액

EX) "0010000000"
error_msg String 에러 발생 시 에러메시지

이어서 계좌개설이 정상적으로 완료되었을 경우 발급받은 인가코드(authorization_code)와 고객식별키(personalseckey)를 사용해서 접근토큰발급을 진행합니다

접근토큰발급 API

POST /oauth2/tokenP

서비스 서버가 Redirect URI를 통해 전달받은 인가코드로 접근토큰발급을 요청합니다.

Request Body

Request Body 목록 Name, Type, Description 정보
Name Type Description
appkey 필수입력
String 제휴사의 앱키

제휴 등록 후 발급받은 제휴사의 앱키
grant_type 필수입력
String 권한부여 타입

"authorization_code" : 법인 권한 부여
appsecret 필수입력
String 제휴사의 비밀키

제휴 등록 후 발급받은 제휴사의 비밀키
personalseckey 필수입력
String 고객식별키

트레이딩 API 에서 활용
code 필수입력
String 인가코드

Redirect URI로 받은 인가코드
corpname 필수입력
String 제휴사코드 or 제휴사명

가급적 제휴사코드로 입력

EX) "12345" or "한국투자증권"

Response Body (접근토큰발급)

접근토큰발급 API 호출 시, KIS Developers는 인가코드를 확인하여 접근토큰(access_token), 갱신토큰(refresh_token)을 발급해 서비스 서버에 전달합니다.

Response Body (접근토큰발급) 목록 Name, Type, Len, Description 정보
Name Type Len Description
access_token String 350 고객 접근토큰

EX) "eyJ9eXAiOi...."
expires_in Long 접근토큰 유효시간(초)(90일) EX) 7776000
access_token_token_expired String 접근토큰 유효기간(일시표시)

EX) "2022-08-30 08:10:10"
refresh_token String 350 고객 리프레쉬 토큰

EX) "eyJ9eXBiXi...."
refresh_token_expires_in Long 리프레쉬 토큰 유효시간(초)(1년 6개월) EX) 48000000
refresh_token_token_expired String 리프레쉬 토큰 유효기간(일시표시)

EX) "2022-08-30 08:10:10"
token_type String 20 토큰 유형

EX) "Bearer"

200:OK

{
    "access_token": "eyJ...qsg",
    "refresh_token_expires_in": 48000000,
    "refresh_token": "eyJ...2nA",
    "access_token_token_expired": "2024-07-14 14:04:07",
    "token_type": "Bearer",
    "refresh_token_token_expired": "2025-10-23 03:24:07",
    "expires_in": 7776000
}
  • 접근토큰과 갱신토큰의 유효시간은 각각 아래와 같습니다.
접근토큰과 갱신토큰의 유효시간 목록 토큰명, 내용, 유효시간(초) 정보
토큰명 내용 유효시간(초)
접근토큰(access_token) 유저 엑세스 토큰 값 7,776,000초 (90일)
갱신토큰(refresh_token) 유저 리프레시 토큰 48,000,000초 (약1년 6개월)

CONFIRM

팝업 닫기

CONFIRM

팝업 닫기

CONFIRM

팝업 닫기

시크릿조회

팝업 닫기

시크릿조회

팝업 닫기

제목

팝업 닫기

KIS Developers 이용약관

팝업 닫기
잠시만 기다려 주세요

마지막 로그인

팝업 닫기