연동준비하기
• 연동가능환경 • 방화벽정보 • 대칭키 • HASH 방법 • AES 암호화

연동파라미터 규격
| INIAPI 샘플코드 | 취소/부분취소   | 빌링(정기과금)   | 에스크로      • 배송등록    • 구매거절확인    • 상태변경노티
| 현금영수증   | 비인증결제   | 포인트결제   | 기타API  


INIAPI


이니시스 결제의 에스크로 배송등록, 구매거절확인 등을 사용하기 위한 API 입니다.

해당 서비스는 OPEN API형태로 구성되어 있으며, 연동 시 상세파라미터 규격에 대하여 안내합니다.


※ 에스크로 결제와 구매결정은 PC(웹표준)결제모듈과 모바일결제 모듈로 진행되어야 합니다.

 
에스크로API Header

POST /api/v1/escrow HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8

API URL: https://iniapi.inicis.com/api/v1/escrow

INIAPI 요청/응답형식

요청형식 : 각 파라미터를 key=value 로 세팅하여 POST로 API 요청  ( JSON방식 요청불가 )
                  Form data 세팅 후 API 통신 구간에서 전체 URLencode 하여 전송

응답형식 : JSON

* 참고)  1. INIAPI 응답파라미터는 추후 요건에 의해 추가될 수 있습니다.
2. 실패 응답시 일부 파라미터 응답이 null 일 수 있습니다.

 
 
 

배송등록


에스크로 결제 승인성공 후, 배송등록을 하기위한 API 입니다.


파라미터 설명 필수(O/X) SIZE(Byte)
type "Dlv" 고정 O 6
mid 상점아이디 O 10
clientIp 가맹점 요청 서버IP (추후 거래 확인 등에 사용됨) O 15
timestamp 전문생성시간 [YYYYMMDDhhmmss] O 14
tid 에스크로 결제 승인TID O 40
oid 주문번호 O 40
price 결제금액 O
report 에스크로 등록형태 ["I":등록, "U":변경] O 1
invoice 운송장번호 O
registName 배송등록자 O
exCode 택배사코드   Code O
exName 택배사명 O
charge 배송비 지급형태 ("SH":판매자부담, "BH":구매자부담) O
invoiceDay 배송등록 확인일자 O
sendName 송신자 이름 O
sendTel 송신자 전화번호 O
sendPost 송신자 우편번호 O
sendAddr1 송신자 주소 1 O
sendAddr2 송신자 주소 2 X
recvName 수신자 이름 O
recvTel 수신자 전화번호 O
recvPost 수신자 우편번호(구분자 없이) O
recvAddr 수신자 주소 1 O
goodsCode 상품코드 X
goods 상품명 X
goodsCnt 상품수량 X
hashData 전문위변조 HASH   HASH
×
hashData 개요

HASH 알고리즘:  SHA-512
대상파라미터 : 각 서비스API 별로 상이

     1> SHA-512 사용합니다.
     2> INIAPI key 를 사용합니다.


SHA512 HASH 생성 확인하기

※ Hash 암호화 데이터 설정의 예시 __ 카드취소 기준

   type = Refund
   paymethod = Card
   timestamp = 20191128121211
   clientIp = 123.123.123.123
   mid = INIpayTest
   tid = StdpayCARDINIpayTest20191128121211123456
   msg = 테스트

   hashData =    b2dc4d4308d836a77187fa1f4ce8c540006a41e6a708a63aded363510c7d445600601c9035825fe32f48fe1b7d2ea130f690a2895a41b6fa0a99c6c5f92d6d69

   (PlainText : ItEQKi3rY7uvDS8lRefundCard 20191128121211123.123.123.123INIpayTest StdpayCARDINIpayTest20191128121211123456)



관련 웹매뉴얼로 이동하기

hash(INIAPIKey+type+timestamp+clientIp+mid+oid+tid+price)
[ INIAPI Key 확인경로 ]
INIAPI Key 확인경로

1) INIAPI 연동 시 mid 파라미터에 세팅한 상점아이디로 가맹점관리자에 로그인 합니다.

2) 상단 메뉴에서 상점정보 > 계약정보 > 부가정보 로 이동합니다.

3) INIAPI key 생성 갱신 에서 "조회" 버튼을 클릭하여 INIAPI key 와 iv 값을 확인합니다.

4) INIAPI key 와 iv 값은 최초 생성 후 갱신하지 않습니다.
   (INIAPI 요청 시 key 와 iv 값이 상이한 경우 오류가 발생됩니다.)


동영상 가이드 확인하기
O 128
파라미터 설명 SIZE(Byte)
resultCode 결과코드["00":성공, 그외 실패] 6
resultMsg 결과메세지 100
resultDate 거래일자 [YYYYMMDD] 8
resultTime 거래시간 [hhmmss] 6
 
 
 

구매거절확인


에스크로 결제건에 대하여 고객이 구매거절한 경우, 판매자의 구매거절확인 처리를 하기위한 API 입니다.


파라미터 설명 필수(O/X) SIZE(Byte)
type "Dncf" 고정 O 6
mid 상점아이디 O 10
clientIp 가맹점 요청 서버IP (추후 거래 확인 등에 사용됨) O 15
timestamp 전문생성시간 [YYYYMMDDhhmmss] O 14
originalTid 에스크로 결제 승인TID O 40
dcnfName 거절 확인 처리자 O N/A
hashData 전문위변조 HASH   HASH
×
hashData 개요

HASH 알고리즘:  SHA-512
대상파라미터 : 각 서비스API 별로 상이

     1> SHA-512 사용합니다.
     2> INIAPI key 를 사용합니다.


SHA512 HASH 생성 확인하기

※ Hash 암호화 데이터 설정의 예시 __ 카드취소 기준

   type = Refund
   paymethod = Card
   timestamp = 20191128121211
   clientIp = 123.123.123.123
   mid = INIpayTest
   tid = StdpayCARDINIpayTest20191128121211123456
   msg = 테스트

   hashData =    b2dc4d4308d836a77187fa1f4ce8c540006a41e6a708a63aded363510c7d445600601c9035825fe32f48fe1b7d2ea130f690a2895a41b6fa0a99c6c5f92d6d69

   (PlainText : ItEQKi3rY7uvDS8lRefundCard 20191128121211123.123.123.123INIpayTest StdpayCARDINIpayTest20191128121211123456)



관련 웹매뉴얼로 이동하기

hash(INIAPIKey+type+timestamp+clientIp+mid+originalTid)
[ INIAPI Key 확인경로 ]
INIAPI Key 확인경로

1) INIAPI 연동 시 mid 파라미터에 세팅한 상점아이디로 가맹점관리자에 로그인 합니다.

2) 상단 메뉴에서 상점정보 > 계약정보 > 부가정보 로 이동합니다.

3) INIAPI key 생성 갱신 에서 "조회" 버튼을 클릭하여 INIAPI key 와 iv 값을 확인합니다.

4) INIAPI key 와 iv 값은 최초 생성 후 갱신하지 않습니다.
   (INIAPI 요청 시 key 와 iv 값이 상이한 경우 오류가 발생됩니다.)


동영상 가이드 확인하기
O 128
파라미터 설명 SIZE(Byte)
resultCode 결과코드["00":성공, 그외 실패] 6
resultMsg 결과메세지 100
dcnfDate 구매거절확인 거래일자 [YYYYMMDD] 8
dcnfTime 구매거절확인 거래시간 [hhmmss] 6
 
 
 

에스크로 상태변경노티


에스크로 주요 변경 시점 에 가맹점 측으로 해당 내역을 통보해주는 기능입니다.

  ex>구매자가 이메일 상에서 구매결정(확정)을 완료 등


노티수신 시 유의사항

1. 이니시스 PG에서 요청했는지 여부(IP로 체크)를 반드시 확인하셔야합니다.

   IP : 203.238.37.15 / 203.238.37.32 / 183.109.71.153

2. 정상 수신 여부를 반드시 응답해주셔야합니다.
   상점 데이터베이스 등록 성공 유무에 따라서 성공시에는 "cd_rslt=0000" 문자열만 응답되어야합니다.

   JSP : out.print("cd_rslt=0000");
   PHP : echo "cd_rslt=0000";
   ASP : response.write "cd_rslt=0000"

3. 에스크로 노티는 10분 간격으로 일괄 전송되는 구조로 한 건의 거래가 10분 내 상태가 변경되면 여러 건의 노티(에스크로 상태별)가 전송 될 수 있습니다.

4. 가맹점에서는 에스크로 노티 데이터를 히스토리로 관리하여 최종 에스크로 상태를 구분해야 합니다.

  ex) 매시간 X0분에 에스크로 노티 전송

  1. 05분 : 에스크로 상태 '2' (배송등록)
  2. 07분 : 에스크로 상태 변경 '3' (구매확인)
  3. 10분 : 에스크로 노티 처리시 배송등록과 구매확인에 대한 노티 전문 모두 전송(한건의 거래에 2번의 노티 전송)
    - 노티 전문은 먼저 등록 요청된 순으로 전송됩니다. (배송등록 → 구매확인)
    - 에스크로 노티 응답 실패시 재전송처리는 10회 수행됩니다.

노티수신URL : 영업담당자를 통해 등록한 URL

HTTP Method : POST
Accept-charset : EUC-KR

<< 상태변경노티 파라미터 >>

파라미터 설명 SIZE(Byte)
id_merchant 에스크로 결제요청 시 상점아이디 10
no_oid 에스크로 결제요청 시 주문번호 40
no_tid 에스크로 결제 승인 TID 40
cl_status 에스크로 상태구분
* 배송등록(2),구매확인(3),자동구매확인(31),강제구매확인(32),구매거절(4),거래취소(8),거절확인(10)
2
dt_req 요청일시 [YYYYMMDDhhmmss] 14
cl_paymethod 에스크로 원 결제수단
* 신용카드(0),ISP(1),계좌이체(16),가상계좌(17)
2
msg_deny 구매거절 사유
* 구매거절시 전달
256
price 거래금액 12
tid_org 원거래 거래번호
* 부분취소된 거래만 전달
40

<< 가맹점 응답파라미터 >>

파라미터 설명 SIZE(Byte)
cd_rslt 결과코드 ["0000":정상처리, "9999":처리실패] 4
msg_rslt 처리 실패시 해당 오류메시지 1000