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));