그룹상담신청
상단으로 이동

KG이니시스

KG이니시스

출금동의서비스

KG이니시스 API를 통해 온라인 전자서명 방식의 출금동의 자료 생성이 가능한 서비스

Quick Guide

샘플 다운로드

개발 언어에 맞는 샘플을
다운로드 받아 주세요.

리턴 URL 수정

요청페이지 도메인과 일치하도록 successUrl, failUrl 값을
수정해 주세요.

테스트 실행 및 결과확인

인증 진행과정과
응답결과를 확인해 주세요.

실제 연동진행

가맹점 실서버 환경에 맞게
연동을 진행해주세요.

연동 준비하기

출금동의서비스 연동 전, 체크해야할 사항을 안내드립니다.

MID상점아이디
계약 완료 여부, 사용 설정 등은 계약담당자 문의
apiKey대칭키
가맹점관리자 ▶ 상점정보 ▶ 계약정보 ▶ KEY 정보 ▶ 부가서비스 연동 KEY 정보 ▶ 출금동의서비스 ▶ [조회] 버튼 클릭

※ [조회] 버튼 미노출 시 계약담당자 문의

※ [도메인 조회] 버튼 클릭해 이용 도메인 최소 1개 등록 필수

방화벽정보
항목 스테이징환경 운영환경
URL stgwthda.inicis.com wthda.inicis.com
IP 183.109.71.168 118.129.210.150
183.109.71.96
PORT 443
연결방향 OUTBOUND
보안 프로토콜 TLSv1.2 미만 브라우저 인증 불가

STEP1출금동의 요청

출금동의 요청정보

  • 출금동의 요청URL : https://wthda.inicis.com/wthda/v1/ui/request
  • Content-Type : application/json;charset=utf-8
  • Method : POST
MID* 상점아이디
10 byte
mTxid* 가맹점 트랜잭션 ID (UTF-8 URLEncoding)
요청시마다 유일값
20 byte
timestamp* 요청 일시
YYYYMMDDHHmmss
14 byte
authHash* 등록된 가맹점 요청 확인을 위한 SHA256 hash 값
대상 : MID + mTxid + timestamp + apikey
apikey : 가맹점 계약 시 발급되는 키 값으로 계약 담당자에게 요청
HASH
N/A
userName* 사용자 이름 (UTF-8 URLEncoding)
N/A
userAcctNo* 사용자 계좌번호
N/A
identifyNo* 생년월일(YYYYMMDD)
8 byte
bankCd* 은행 코드
은행코드
N/A
agencyCd* 전자서명 제휴사 코드
제휴사 코드
N/A
phoneNum* 휴대폰 번호
N/A
autopaySvc * 자동이체 서비스 종류 (UTF-8 URLEncoding)
[지로, CMS, 펌뱅킹]
N/A
usingORGCd 이용기관코드
[지로 : 7자리 숫자 / CMS : 10자리 숫자 / 펌뱅킹 : 20자리 이내 영숫자]
N/A
payerNum 납부자 번호
N/A
payerDate 납부자 신청일자 (YYYYMMDD)
N/A
addidentifyNum 부가식별번호
N/A
userHash * 사용자 위변조방지를 위한 SHA256 hash 값
대상 : userName + MID + userAcctNo + mTxid + bankCd + timestamp
HASH
N/A

STEP 2출금동의 응답

※ 유의사항

  1. 정상처리 일 경우는 응답필드가 전부 전송됩니다.
  2. 처리결과에 따라 resultCode, resultMsg 이외의 값은 전송되지 않을 수 있습니다.
resultCode 결과코드
"0000":성공, 이외 실패
4 byte
resultMsg 결과메시지 (UTF-8 URLEncoding)
500 byte
statusReqUrl 인증 상태 조회 요청 URL
이니시스 제공 URL이 맞는지 필수 검증 필요
200 byte
txid 출금동의 트랜잭션 ID
고유값
40 byte
token 암호화 Token 값
Base64 Encoding
N/A

STEP 3인증상태 조회 요청

인증상태 조회 요청정보

  • 인증상태 조회 요청 URL : STEP2 출금동의응답 수신 시 응답 된 statusReqUrl
  • Method : POST
  • 인증상태 조회는 반드시 HTTPS( SERVER to SERVER ) 로 통신해야 합니다.
  • Content-Type : application/json;charset=utf-8
MID* 상점아이디
10 byte
txid* 출금동의 트랜잭션 ID
STEP2 출금동의응답으로 수신받은 값
40 byte

STEP 4인증상태 응답

※ 유의사항

해당 응답파라미터는 모든 인증 프로세스 종료 후 최종적으로 전달되는 응답파라미터 입니다.

  1. 정상처리 일 경우는 응답필드가 전부 전송됩니다.
  2. 처리결과에 따라 resultCode, resultMsg 이외의 값은 전송되지 않을 수 있습니다.
resultCode 결과코드
"0000":성공, 이외 실패
N/A
resultMsg 결과메세지 (UTF-8 urlEncoding)
N/A
txid 출금동의 트랜잭션 ID
N/A
authReqUrl 결과 조회 요청 URL
200 byte

STEP 5출금동의 결과조회 요청

출금동의 결과조회 요청정보

  • 인증상태 조회 요청 URL : STEP4 인증상태응답 수신 시 응답 된 authReqUrl
  • Method : POST
  • 인증상태 조회는 반드시 HTTPS( SERVER to SERVER ) 로 통신해야 합니다.
  • Content-Type : application/json;charset=utf-8
MID* 상점아이디
10 byte
txid* 출금동의 트랜잭션 ID
STEP2 출금동의응답으로 수신받은 값
40 byte

STEP 6결과조회 응답

※ 유의사항

해당 응답파라미터는 모든 인증 프로세스 종료 후 최종적으로 전달되는 응답파라미터 입니다.

  1. 정상처리 일 경우는 응답필드가 전부 전송됩니다.
  2. 처리결과에 따라 resultCode, resultMsg 이외의 값은 전송되지 않을 수 있습니다.
resultCode 결과코드
"0000":성공, 이외 실패
N/A
resultMsg 결과메세지 (UTF-8 urlEncoding)
N/A
txid 출금동의 트랜잭션 ID
N/A
bankCd 은행코드
은행코드
200 byte
acctNo 계좌번호
SEED 암호화
복호화
N/A
phoneNum 휴대폰번호
SEED 암호화
복호화
N/A
userCi 사용자 CI
SEED 암호화
복호화
N/A
autopayInfo 자동납부등록정보 DER
N/A

CODE결과 코드

결과코드 결과메세지 비고
0000정상처리되었습니다.
0001비즈니스서비스-path 정보를 확인할 수 없습니다.
0002실명인증-프로세서 정보를 확인할 수 없습니다.
0003전자서명 토큰발급-프로세서 정보를 확인할 수 없습니다.
0004전자서명 요청-프로세서 정보를 확인할 수 없습니다.
0005전자서명 상태-프로세서 정보를 확인할 수 없습니다.
0006전자서명 결과-프로세서 정보를 확인할 수 없습니다.
0007전자서명 사용자 정보조회-후처리 프로세서 정보를 확인할 수 없습니다.
0008전자서명 후처리-프로세서 정보를 확인할 수 없습니다.
0009조회(check)-프로세서 정보를 확인할 수 없습니다.
0010실명인증-프로세서를 선택할 수 없습니다. (테스트 MID만 선택가능)
0011기준정보조회 연결중 오류
0012실명조회 연결중 오류
0013전자서명 토큰발급 통신 연결중 오류
0014전자서명 요청 통신 연결중 오류
0015전자서명 상태 통신 연결중 오류
0016전자서명 결과 통신 연결중 오류
0017전자서명 결과 후속 작업 통신 연결중 오류
0021이용 가능한 중개사가 없습니다. 관리자에게 문의해주세요.
0022제휴사 키 정보 조회 실패
0023txid가 누락되었습니다.
0024req_trns_id가 누락되었습니다.
0025orn_trns_id가 누락되었습니다.
0026전자서명 결과 정보를 찾을 수 없습니다.
0027전자서명 값이 존재하지 않습니다.
0028전자서명 값 디코딩에 실패했습니다.
0031기준정보조회 실패
0032전자서명 토큰발급 실패
0033전자서명 요청 실패
0034전자서명 상태조회 실패
0035전자서명 결과조회 실패
0041실명조회 실패
0042예금주가 일치하지 않습니다.
0071실명조회 DB INSERT 실패
0072전자서명 요청 DB INSERT 실패
0073전자서명 상태조회 DB INSERT 실패
0074전자서명 결과조회 DB INSERT 실패
0081JSON 파싱 실패
0082암호화 처리 실패
0083복호화 처리 실패
0084인코딩 처리 실패
0098중계사 통신 연결에 실패했습니다. 관리자에게 문의해주세요.
0099처리중 오류가 발생하였습니다. 관리자에게 문의하세요.
9000비정상적인 접근입니다. 처음부터 다시 시도하여 주십시오.
9001중복된 주문번호입니다.
9002필수 요청 값이 누락되었습니다.
9003데이터 사이즈 오류입니다.
9004데이터가 올바르지 않습니다.
9005유효하지 않은 도메인입니다.
9006출금동의 서비스 미사용 가맹점입니다.
9007금융인증서는 API방식을 지원하지 않습니다.
9008요청한 페이지를 찾을 수 없습니다.
9009요청에 대한 인증이 필요합니다.
9010요청에 대한 권한이 필요합니다.
9011이미 처리된 요청입니다.
9012잘못된 요청이 전달되었습니다.
9013잘못된 UI 요청입니다.
9014잘못된 API 요청입니다.
9015요청이 올바르지 않습니다.
9016파라미터가 잘못되었습니다.
9017JSON 형식이 올바르지 않습니다.
9018지원하지 않는 요청 방식입니다.
9019요청한 형식을 처리할 수 없습니다.
9020지원하지 않는 미디어 타입입니다.
9021처리할 수 없는 요청입니다.
9022요청이 너무 많습니다.
9023서버에서 오류가 발생했습니다.
9024구현되지 않은 기능입니다.
9025서버 호출 중 오류가 발생했습니다.
9026서버 내부 I/O 문제가 발생했습니다.
9027외부시스템 오류가 발생했습니다.
9028서비스 이용 불가
9029시간 내에 요청이 처리되지 않았습니다.
9030외부 시스템 응답이 지연되었습니다.
9100토큰 생성에 실패했습니다.
9200예금주가 일치하지 않습니다.
9300인증 기록이 존재하지 않습니다.
9301결과조회 요청은 최초 1회만 가능합니다.
9302전자서명 값 검증에 실패하였습니다.
9500기준정보 조회에 실패했습니다. 관리자에게 문의하세요.
9997URL Redirect 과정중 오류가 발생했습니다. 관리자에게 문의하세요.
9998DB 처리 중 오류가 발생하였습니다. 관리자에게 문의하세요.
9999처리중 오류가 발생하였습니다. 관리자에게 문의하세요.