INIAPI 

모듈연동 FAQ

모듈연동에 대한 궁금증을 해결해 보세요.
INIAPI 는 REST API 로, 정의된 API URL 에 필수파라미터를 key=value 형태로 
나열하여 POST 로 데이터 전송하는 모듈입니다.(JSON 방식으로는 데이터 전송이 불가합니다.)

관련하여 웹매뉴얼에 자세한 연동규격 및 샘플코드 안내되어 있으므로 매뉴얼 참고부탁드립니다.

매뉴얼 : https://manual.inicis.com/iniapi/

INIAPI 매뉴얼 아래와 같이 [ENC] 표기가 파라미터가 AES 암호화 대상입니다.

 

 

특정파라미터에 [ENC] 표시가 있다면 반드시 value 값을 AES암호화 세팅해주시기 바랍니다.

 

ex) 조건 : 환불계좌번호=123456789, MID=INIpayTest

refundAcctNum = qwMHVJqsmXKoR+d8wQTS4g==

 

 

*** 주의 ***

 

– hashData 생성 시에도 refundAcctNum 부분에 AES암호화 값을 세팅하셔야 합니다.

 

– api 통신구간에서 요청전문을 반드시 urlencode 하셔야 합니다.

  (urlencode 하지 않을 경우 AES 암호화데이터 특수문자(+) 누락될 있습니다.)

 

 

INIAPI 에서 사용되는 key  signkey  아닌 INIAPI key  사용됩니다.
signkey INIpay standard(PC) 모듈에서만 사용되는 key 값입니다.

따라서 INIAPI 연동 해당 MID 상점관리자에 접속하여
별도의 INIAPI key 확인하시기 바랍니다.


[INIAPI 확인경로]
상점관리자 > 상점정보 > 계약정보 > 부가정보 > INIAPI key 생성 갱신


참고로, INIAPI 매뉴얼 상에 INIAPI key 확인경로 테스트 상점아이디의 INIAPI key
안내되어 있습니다.

매뉴얼 : https://manual.inicis.com/iniapi/api-info.html#iniapikey

 

INIAPI 요청 API URL 오세팅 경우, 정상응답이 전달되지 않고 URL 응답됩니다.

 

API URL 아래와 같이 https:// (프로토콜) + HOST + API 경로 세팅해주셔야 합니다.

 

https://iniapi.inicis.com/api/v1/(서비스)/

 

ex) 결제/승인 취소 api 요청

https://iniapi.inicis.com/api/v1/refund/

 

1. 운영계 거래건을 개발계로 취소요청할 경우 오류발생

 

PC웹표준 또는 모바일 모듈로 결제완료 후

INIAPI 거래취소 모듈로 취소요청 시 운영환경으로 취소요청 해야합니다.

취소요청URL 을 운영환경 (https://iniapi.inicis.com/api/v1/refund) 으로 세팅하여 재시도 바랍니다.

 

** PC웹표준 모듈에서 테스트JS 로 결제요청 하더라도 실 승인은 운영계로 처리되므로 취소요청 시 운영계로 요청해야만 정상처리됩니다.

 

 

2. 인증TID 로 취소요청할 경우 오류발생

 

모바일 모듈의 경우 인증TID 와 승인TID 로 TID 가 2번 전달됩니다.

 

인증TID –> INIMX_AUTH

승인TID –> INIMX_CARD / INIMX_ISP

 

인증TID 는 실결제에 대한 TID 가 아니므로 승인TID 로 취소요청 바랍니다.

 

 

3. 취소요청 TID 에 오타 또는 누락된 부분이 있을 경우 오류발생

 

취소요청 하는 거래건TID 가 올바른지 재확인 바랍니다.

 

 

위 내용으로 오류확인이 되지 않는 경우

거래건 TID 또는 당사로 거래요청 시 세팅한 파라미터 값 전체를 하기 메일로 첨부하여 문의부탁드립니다.

 

기술지원 : ts@kggroup.co.kr

INIAPI 경우 대소문자를 체크합니다.

따라서 파라미터명과 value 세팅 반드시 매뉴얼에 안내된 대소문자를 구분하여 세팅하셔야 합니다.

value 세팅된 값에 대소문자가 맞지않는 경우, ERR012 오류가 발생될 있습니다.

ex) paymethod = card ( X ) –> Card ( O )

1. 암호화 대상 필드의 값이 암호화되지 않은 상태로 거래요청 된 경우 오류발생

 

매뉴얼 내 파라미터 설명 부분에 “ENC” 표기가 있는 경우 AES암호화 전송해야 합니다.

 

ex) 가상계좌 환불 모듈 내 “환불계좌번호”

 

2. 암호화 시 사용한 KEY 또는 IV 값이 누락되거나 상이할 경우 오류발생

 

MID 와 매칭되는 KEY 값과 IV 값을 통해 암호화 한 것이 맞는지 확인합니다.

 

KEY 와 IV 는 상점관리자페이지(https://iniweb.inicis.com)에서 확인가능합니다.

–> 상점정보 > 계약정보 > 부가정보 > INIAPI key 생성 갱신

 

 

위 내용으로 오류확인이 되지 않는 경우,

당사로 거래요청 시 세팅한 파라미터 값 전체를 하기 메일로 첨부하여 문의부탁드립니다.

 

기술지원 : ts@kggroup.co.kr

hashdata 불일치 오류가 발생되는 경우, 요청 파라미터 내 세팅된 값과
hashdata 생성 시 PlainText (평문데이터) 값이 일치하는지 비교검토가 필요합니다.

hash 대상 파라미터는 각 API 별로 상이하며, 결제/승인 취소 API 를 통해 예시 드립니다.

ex) 결제/승인 취소 API
URL = https://iniapi.inicis.com/api/v1/refund

————————————————————————————————-
[요청파라미터]
type = Refund
paymethod = Card
timestamp = 20191128121211
clientIp = 123.123.123.123
mid = INIpayTest
tid = StdpayCARDINIpayTest20191128121211123456
msg = 테스트
hashdata = b2dc4d4308d836a77187fa1f4ce8c540006a41e6a708a63aded363510c7d445600601c
9035825fe32f48fe1b7d2ea130f690a2895a41b6fa0a99c6c5f92d6d69
————————————————————————————————–

PlainText :
ItEQKi3rY7uvDS8lRefundCard20191128121211123.123.123.123INIpayTest
StdpayCARDINIpayTest20191128121211123456

SHA512 hash :
b2dc4d4308d836a77187fa1f4ce8c540006a41e6a708a63aded363510c7d445600601c
9035825fe32f48fe1b7d2ea130f690a2895a41b6fa0a99c6c5f92d6d69

위와 같이 정상 세팅했음에도 오류가 발생되는 경우,

mid 와 매칭되는 API KEY 값으로 hash 한 것이 맞는지 확인이 필요합니다.

가맹점관리자페이지https://iniweb.inicis.com/ 에서 상점정보 > 계약정보 > 부가정보 > INIAPI KEY 생성 갱신

오류원인 확인이 어려우신 경우 호출한 하기내용 첨부하여 ts@kggroup.co.kr 으로 문의바랍니다.

호출 URL :
요청파라미터 :
PlainText :

1) MID 의 INIAPI key 가 생성되었는지 확인

상점관리자 > 상점정보 > 계약정보 > 부가정보 > INIAPI key 생성 갱신

위 경로에서 확인되는 key 값으로 모듈에 세팅하였는지 확인바랍니다.

2) 실운영 MID 로 거래요청 시 운영계 URL 세팅여부 확인
운영계 URL = https://iniapi.inicis.com

실운영 MID 로는 개발계 URL 로 거래요청이 불가합니다.

위 내용으로 원인확인이 되지 않는 경우,

API URL 과 전체 파라미터 세팅값을 첨부하여 ts@kggroup.co.kr 로 문의바랍니다.

오류메세지와 같이 mid 값이 세팅되지 않았거나, 파라미터명이 오세팅 된 경우 발생되는 오류입니다.

또는 INIAPI 모듈에서 지원하지 않는 방식으로 전문전송 경우에도 발생될 수 있습니다. (JSON 방식 등)

INIAPI 의 경우 JSON 방식으로 데이터 전송이 불가하며,

key=value 형태의 파라미터를 POST로 요청해야합니다.

** PHP 언어로 연동 시 

PHP에서 POST요청을 curl로 처리할 때 배열의 파라미터가 제대로 전달되지 않는 경우에 mid is null 오류가 발생할 수 있습니다.

이 경우, http_build_query() 함수를 사용하여 URL 인코딩된 쿼리 문자열을 생성하신 후 재시도바랍니다.

 

ex) curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($form_data));