🦅통합간편결제 통신 API

케이아이에스정보통신(주) 와 통합간편결제 통신하는 모듈입니다.

Windows API

본 문서는 KIS정보통신의 인터넷 승인 결제 라이브러리의 설명서입니다.

주의 사항

1. 함수의 리턴값이 0인 경우는 응답 전문을 수신한 경우이며 정상승인과는 별개입니다.

리턴값이 0인 경우에도 승인 거절일 수도 있습니다.

1. 함수의 리턴값이 99,98,97인 경우 망상취소가 발생한 경우이며 DLL에서 자동망상취소전문 생성하여 HOST로 전송하지만 자동망상취소 실패 시에는 반드시 POS프로그램에서 망상 취소전문(통신장애전문)을 생성하여 HOST로 전송하여야 합니다.

2. 멀티 스레드의 경우 거래일련번호 생성 시 파일에 접근하는 업무가 있으므로 불안정합니다. 단일 스레드를 사용해야 합니다.

3. 거래 일련 번호는 DLL에서 별도로 저장된 거래일련번호로 대치되어 사용되어지므로 유의하시기 바랍니다

4. POS프로그램의 개발 언어가 Visual Basic계열(파워빌더포함)인 경우 함수명은 VB_로 시작하는 함수를 호출하여 주시기 바랍니다.

5. 이 모듈은 KIS정보통신 전문포맷 사양서만 지원합니다.

KIS_Approval_EasyPay API

Name	Type	Description
inIpAddress	String	IP 주소
inPortNo	int	Port 번호
inGourpCode	String	그룹코드(ex: "" )
inSendData	char *	결제요청 데이터
inSendLen	int	결제요청 데이터 길이
inSignGubun	String	서명데이터 구분(ex: B - BMP파일)
inSignData	String	서명데이터
inSignLen	int	서명데이터 길이
outRecvData	char *	결제응답 데이터

Retrun Value

[0] 정상적으로 응답전문 수신

[2] 사인데이터 사이즈가 1700byte일때, (재 서명 요청하여 주십시오)

[-21, -23] 네트워크 오류 KIS서버 접속 실패. 망상처리 안함

[99] Timeout발생 후 DLL에서 자동 망상 처리가 성공한 경우 (취소가 거절될 수 있음)

[98] Timeout발생 후 DLL에서 자동 망상 처리가 Timeout된 경우.

[97] Timeout발생 후 DLL에서 자동 망상 처리할 수 없는 경우 (예, 신용취소)

요청데이터

Type	Name	Length	Description
String	inStructVer	3	전문버전(V02)
String	inTranCode	2	전문구분 AC : 승인, RR : 취소, R2 : 망취소, IQ : 조회
String	inCatId	10	단말기번호
String	inStoreCode	6	그룹코드
String	inAgencyCode	3	포스관리번호
String	inTranNo	20	거래고유번호
String	inTradeReqTime	14	요청일자시간
String	inAppPayGubn	14	간편결제구분
String	inCardNo	256	인증코드번호 바코드길이(3)+바코드번호+'^'+DEVICEID(10) ex) 카카오페이 : 024281006100000000023456789^1234567890
String	inYNSign	1	전자서명유무
String	inHeaderFiler	50	헤더 여부필드
String	inWCC	1	입력방식
String	inCurrencyCode	3	통화코드
String	inInstallment	2	할부개월
String	inTranAmt	12	결제요청금액
String	inVatAmt	12	부가세
String	inSvcAmt	12	봉사료
String	inTreeAmt	12	비과세금액
String	inExchangeAmt	14	환율적용금액
String	inExchangeInfo	8	환율정보
String	inOrgAuthDate	8	원승인일자
String	inOrgAuthNo	32	원승인번호(원주문번호)
String	inVanKey	16	VANKEY
String	inDeviceAuthValue	32	인증식별번호
String	inPinBlock	16	비밀번호
String	inAddInfo	100	부가정보
String	inReqFiller	93	FILLER
String	inDepositAmt	7	컵보증금
String	inAddInfo2	200	길이(4)+부가정보(MAX 196) *이디야 기프트카드정보 ( (카드번호(16)*10) + 구분자(9) = 최대169 ) -> "0169"+DATA

응답 데이터

Type	Name	Length	Description
String	outStructVer	3	전문버전
String	outTranCode	2	전문구분
String	outCatId	10	단말기번호
String	outStoreCode	6	그룹코드
String	outAgenyCode	3	포스관리번호
String	outTranNo	20	거래고유번호
String	outTradeReqTime	14	요청일자시간
String	outTradeResTime	14	응답일자시간
String	outAppPayGubn	3	간편결제구분
String	outCardNo	256	인증코드번호
String	outReplyCode	4	응답코드
String	outDisplayMsg	50	응답메시지
String	outYNSign	1	서명여부
String	outHdrFiller	50	요청헤더필드
String	outAuthNo	32	승인번호
String	outOrderNo	32	주문번호(알리/위쳇) 취소시 필수 주문번호 (고객영수증에 출력하며 취소시 사용)
String	outAddedPoint	12	발생포인트(할인금액)
String	outUsablePoint	12	가용포인트(승인금액) 카카오페이 : 결제요청금액 - 카카오페이할인금액
String	outTotalPoint	12	누적포인트(잔액한도) SSGPAY : SSG MONEY 잔액
String	outPayMethod	5	결제수단 카카오 : ‘MONEY’ / ‘CARD’ SSGPAY : ‘MONEY’/ ‘CARD’ / 'ACCOT' TOSSPAY : ‘MONEY’/ ‘CARD’ / 'ACCOT' (머니/카드/계좌)
String	outUserID	16	USER ID
String	outMerchantRegNo	20	가맹점번호
String	outAccepterCode	4	매입사코드
String	outAccepterName	16	매입사명
String	outIssuerCode	4	발급사코드
String	outIssuerName	16	발급사명
String	outMemBarcodeNo	16	멤버쉽바코드
String	outMemMerchantNo	20	가맹점멤버쉽번호
String	outOTC	40	OTC정보 카카오페이 : 카드 승인시 SSG페이 -SSG PAY 취소 바코드 번호: ‘취소바코드: ‘ + 바코드번호 -OTC 번호 요청 시 : ‘실제 승인 OTC번호=유효기간’ -SSG계좌 은행사명 EMVQR결제시 : OTC
String	outCardBin	8	실카드BIN 카카오페이 : 카드 승인시 LPAY
String	outVanKey	16	VANKEY
String	outAddInfo	100	부가정보 SSGPAY SSG PAY 마스킹 실카드번호: ‘실카드: ‘ + 0000---0000 SSG계좌 가상계좌출력번호: ‘가상계좌: ’ + 123456789012345 LPAY LPAY에 등록된 결제요청ID(20) : 가맹점에서 LPAY와 대사 필요시 가맹점저장 신한은련MPM(정상일 경우) 할인후금액(12)+할인금액(12)+결제금액(12)
String	outCardGubun	1	신용/체크 구분 0 : 신용, 1 : 체크, 2 : 기프트/선불
String	outPurchaseGubun	1	DDC구분 D : DDC, S : DESC, C : EDC
String	outFiller1	98	FILLER1

JAVA Class 구성

Class 명	Package	설명
KisvanSpec	kr.co.kisvan.lib	KIS정보통신 전문생성을 도와주는 Class
Kisvan	kr.co.kisvan.lib	KIS정보통신 서버와 통신하는 Class
KisvanSign	kr.co.kisvan.lib	KIS정보통신 암호화 서명데이터 생성 Class

Kisvan Class

함수목록

함수명	설명	Retrun Type
Kisvan_Init	초기화
Kisvan_Approval	승인요청	-11 : 요청데이터 확인요망 -12 : 요청전문암호화 실패(KEY생성오류) -13 : 요청전문암호화 실패 -14 : 응답전문복호화 실패(KEY생성오류) -15 : 응답전문복호화 실패 -16 : 응답전문 길이 오류 -17 : 서명 암호화 오류 -18 : 서명 관련 데이터 확인 요망 -21 : Server Connect Error -22 - -23 : Socket Send Error -24 - -27 : Socket Read Error

Request

Name	Type	Description
inServerIP	String	서버IP
inServerPort	int	서버포트
inCryptType	int	"0"평문,"1"SEED
inSpecType	String	참조, 개발가이드
inReqSpec	String	요청 데이터
inReqSpecLen	int	요청 데이터 길이
inSignType	int	"0"서명안함, "1"NOCVM, "2"암호화서명데이터, "3"BITMAP데이터
inSignData	Byte[]	서명 데이터
inSignDataLen	int	서명 데이터 길이

Response

Name	Type	Description
outResSpec	Byte[]	응답전문
outResSpecLen	int	응답전문 길이

KisvanSpec Class

Kis 전문 생성을 도와주는 함수

함수목록

함수명	설명	Return Type
Init	초기화
MakeReqSpec	요청전문 생성	"0":정상 "-1":요청데이터 확인요망 "-2":지원하지 않는 전문 Type "-3":지원하지 않는 거래 Type
GetResSpec	응답전문 Slice	"0":정상 "-2":지원하지 않는 전문 Type "-3":지원하지 않는 거래 Type "-4":요청전문 메모리 부족 "-5":응답전문 확인 요망

KisvanSign Class

Kis 서명암호화 함수

Name	설명	Return Type
EncryptSignData	서명암호화	"0 보다 큰경우":데이터길이 "-1":서명데이터 읽기 실패 "-2":서명Type 오류

Request

Name	Type	Description
inSignType	int	3 : BITMAP(Header제외) 4 : FilePath(서명파일경로 전달)
inSignData	Byte[]	BMP인 경우 사용
inSignFileName	String	BMP FilePath인 경우 사용

Response

Name	Type	Description
outSignData	Byte[]	암호화된 서명데이터

KisvanSpec 상세요청

Type	Name	Length	Description
String	inServerIP	21	테스트 : 210.112.100.97
String	inServerPort	6	테스트 : 60110
String	inSpecType	2	스펙구분 KisvanSpec.SPEC_TYPE_SIMPLEPAYMENT
String	inCatId	10	가맹점단말기번호
String	inAgencyCode	3	개발업체구분
String	inTranCode	2	전문구분코드 AC : 승인, RR:취소
String	inWCC	1	"S" : SWIPE, "K" : KEY_IN, "C" : IC, "B" : BarcodeNumber
String	inBarcodeNumber	256	길이(3)+인증번호(바코드번호) ex>021111111111111111111111
String	inTotAmt	12	* 카카오페이 카드 취소 CARD일 경우 실승인금액 (할인전금액-할인금액)
String	inVatAmt	12	부가세
String	inSvcAmt	12	봉사료
String	inTaxFree	12	면세금액
String	inInstallment	2	할부
String	inCurrencyCode	3	통화코드
String	inExchangeRateInformation	8	통화정보
String	inExchangeRateAmt	14	통화금액
String	inOrgAuthNo	32	* 취소시 원승인번호 * 알리/위챗페이 - 주문번호 사용
String	inOrgAuthDate	8	취소시 원거래일자 ( YYYYMMDD )
String	inVanKey	6	밴키
String	inDeviceAuthValue	32	인증식별번호
String	inPwd	16	비밀번호
String	inAdditionalInfo	100	- 저장필요 정보 (ex. 병원정보) - 알리/위챗 : 승인시 구매상품명 (영문)
String	inFiller2	100	여유필드
String	context		Context 안드로이드 11버전 이상에서 거래일련번호를 생성 할 수 없는 경우 Context 생성하여 전달
String	indepositAmt	7	컵보증금
String	inHospitalInfo	V(196)	병원정보 데이터(MAX(200))

KisvanSpec 상세응답

Type	Name	Length	Description
String	outReplyCode	4	응답코드
String	outReplyMsg1	50	응답메시지
String	outAuthNo	32	승인번호
String	outOrderNo	32	알리/위챗 : 주문번호 (고객영수증에 출력하며 취소시 사용)
String	outMerchantRegNo	20	카드사 가맹점번호
String	outMemberShipBarcodeNumber	16	멤버쉽바코드
String	outAccepterCode	2	매입사코드
String	outAccepterName	20	매입사명
String	outIssuerCode	2	발급사코드
String	outIssuerName	20	발급사명
String	outAddedPoint	12	발생포인트(할인금액) 카카오페이 : 할인금액
String	outUsablePoint	12	가용포인트(승인금액) 카카오페이 : 결제요청금액 - 카카오페이할인금액
String	outTotalPoint	12	누적포인트(잔액한도) SSGPAY : SSG MONEY 잔액
String	outPayGubun	5	결제수단 카카오 : ‘MONEY’ / ‘CARD’
String	outUserID	32	구매 USER ID 알리 : 사용자ID
String	outOTC	40	OTC정보 * 카카오페이 : 카드 승인시 * SSG페이 - SSG PAY 취소 바코드 번호: ‘취소바코드: ‘ + 바코드번호 - OTC 번호 요청 시 : ‘실제 승인 OTC번호=유효기간’ - SSG계좌 은행사명
String	outCardNo	8	실카드BIN 카카오페이 카드 승인시
String	outVanKey	16	VANKEY
String	outFiller	100	부가정보 * SSGPAY - SSG PAY 마스킹 실카드번호: ‘실카드: ‘ + 0000-****-****-0000 - SSG계좌 가상계좌출력번호: ‘가상계좌: ’ + 123456789012345
String	outFiller2	100	FILLER1
String	outAuthDate	8	승인일자 승인일자(YYYYMMDD)
String	outPayType	3	간편결제구분 [응답] 결제구분 ‘KKO’ : 카카오페이 ‘SGP’ : SSGPAY ‘ZRP’ : 제로페이 ‘ALP’ : 알리페이 ‘WEP’ : 위챗페이 'LPY' : LPAY 'APP' : 앱카드 * 인증코드번호가 없는 요청시 반드시 세팅

참고>

1. jarKisvan 개발가이드(별첨).xlsx 파일 참조