INIAPI 소개

이니시스 결제의 승인/취소/부분취소 등을 사용하기 위한 API 입니다.

INIAPI는 보안을 위해 HTTPS를 사용하며, TLS v1.2만 지원합니다.
 

방화벽정보

INIAPI 서비스 위해서는 아래 정보에 대해 방화벽 허용이 필요 합니다.
개발환경에서는 테스트 MID(INIpayTest, INIBillTst)만 사용 가능합니다.
항목 내용
개발 환경 deviniapi.inicis.com
203.238.37.19
스테이징 환경 stginiapi.inicis.com
118.129.210.153
운영 환경 iniapi.inicis.com
118.129.210.166, 183.109.71.79
PORT 443

대칭키

INIAPI는 필드 암호화 및 전문 Hash를 위해 대칭키를 사용합니다
KEY와 IV는 상점관리자새 창에서 생성/조회 가능합니다.

> 상점정보 > 계약정보 > 부가정보 > INIAPI Key
key16
<<테스트MID 대칭키>>
KEY는 데이터 암호화 및 hash 생성에 사용되며, IV는 데이터 암호화에 사용됩니다
MID KEY IV
INIpayTest ItEQKi3rY7uvDS8l HYb3yQ4f65QL89==
INIBillTst rKnPljRn5m6J9Mzz W2KLNKra6Wxc1P==
iniescrow0 yERbIlJ3NhTeObsA tOGDXbfoajk2DQ==
 

암호화

INIAPI는 주요 데이터는 암호화하여 전송하며, 암호화 알고리즘은 AES(AES/CBC/PKCS5Padding)를 사용합니다.
 

API 요청

API 요청 형식은 아래와 같습니다.
(예시)
curl -X POST {API_URL} \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
--data-urlencode 'field1=data1' \
--data-urlencode 'field2=data2' \
--data-urlencode 'field3=data3' \
--data-urlencode 'field4=data4' \
(파라미터는 각 API별로 상이합니다.)
 

hash 검증

INIAPI는 요청전문 위변조 확인을 위해 hash를 생성합니다.
hash 알고리즘은 SHA-512를 사용하며, hash에 필요한 PlainText는 각 API별로 상이합니다.
 

API 목록

 

취소/환불

이니시스 거래에 대한취소/환불 및 부분취소/부분환불에 대해 안내합니다.

취소/환불 API는 신용카드/계좌이체/휴대폰 거래와 가상계좌 거래를 구분하여 처리합니다.
다만, 계좌이체와 휴대폰 거래의 환불은 거래특성상 "환불받을 계좌"가 필요한 경우가 있어 별도로 안내합니다.
POST /api/v1/refund HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8

결제/승인 취소

<<요청 파라미터>>
설명 SIZE 필수
type "Refund" 고정 6
paymethod 지불수단 코드info 10
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6

결제/승인 부분취소

<<요청 파라미터>>
설명 SIZE 필수
type "PartialRefund" 고정 13
paymethod 지불수단 코드info 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
price 환불요청금액 10
confirmPrice 재승인요청금액 10
currency 통화코드 (WON/USD) 3
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+price+confirmPrice)
128
<<응답 파라미터>>
Property 설명 SIZE Require
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
prtcTid 원거래번호 40
tid 부분환불TID 40
prtcPrice 취소 금액 12
prtcRemains 재승인금액 12
prtcCnt 부분환불 요청 횟수 2

계좌이체 환불

<<요청 파라미터>>
설명 SIZE 필수
type "Refund" 고정 6
paymethod "Acct" 고정 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
refundAcctNum 환불계좌번호ENC (국민은행 i계좌이체 거래인 경우) 40
refundAcctName 환불계좌 예금주명 (국민은행 i계좌이체 거래인 경우) 20
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+refundAcctNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6
cshrCancelNum 10

계좌이체 부분환불

<<요청 파라미터>>
설명 SIZE 필수
type "PartialRefund" 고정 13
paymethod "Acct" 고정 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
refundAcctNum 환불계좌번호ENC (국민은행 i계좌이체 거래인 경우) 40
refundAcctName 환불계좌 예금주명 (국민은행 i계좌이체 거래인 경우) 20
price 환불요청금액 10
confirmPrice 재승인요청금액 10
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+price+confirmPrice+refundAcctNum)
128
<<응답 파라미터>>
Property 설명 SIZE Require
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6
prtcTid 원거래번호 40
tid 부분환불TID 40
prtcPrice 취소 금액 12
prtcRemains 재승인금액 12
prtcCnt 부분환불 요청 횟수 2

가상계좌 환불

<<요청 파라미터>>
설명 SIZE 필수
type "Refund" 고정 6
paymethod "Vacct" 고정 5
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
refundAcctNum 환불계좌번호ENC 40
refundBankCode 환불계좌은행코드 2
refundAcctName 환불계좌 예금주명 20
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+refundAcctNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6
prtcTid 원거래번호 40
tid 부분환불TID 40
prtcPrice 취소 금액 12
prtcRemains 재승인금액 12
prtcCnt 부분환불 요청 횟수 2

가상계좌 부분환불

<<요청 파라미터>>
설명 SIZE 필수
type "PartialRefund" 고정 13
paymethod "Vacct" 고정 5
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
refundAcctNum 환불계좌번호ENC 40
refundBankCode 환불계좌은행코드 2
refundAcctName 환불계좌 예금주명 20
price 환불요청금액 10
confirmPrice 재승인요청금액 10
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+price+confirmPrice+refundAcctNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6
prtcTid 원거래번호 40
tid 부분환불TID 40
prtcPrice 취소 금액 12
prtcRemains 재승인금액 12
prtcCnt 부분환불 요청 횟수 2

휴대폰 환불

* 휴대폰 익월환불은 영업담당자를 통해 별도 계약 후 사용가능합니다.
<<요청 파라미터>>
설명 SIZE 필수
type "Refund" 고정 6
paymethod "HPP" 고정 3
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
refundAcctNum 환불계좌번호 (익월환불의 경우)ENC 40
refundBankCode 환불계좌 은행코드 (익월환불의 경우) 2
refundAcctName 환불계좌 예금주명 (익월환불의 경우) 20
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+refundAcctNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
cancelDate 취소일자 8
cancelTime 취소시간 6

빌링(정기과금)

빌링(정기과금)을 위한 빌링키발급/빌링승인 연동에 대해 설명합니다.

* 해당 API는 비인증 방식으로 영업담당자를 통해 별도 계약 후 사용가능합니다.
POST /api/v1/billing HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8

빌링키 발급

* 해당 API는 비인증 방식으로, 로그인 후 확인 가능합니다.

빌링 승인

<<요청 파라미터>>
설명 SIZE 필수
type "Billing" 고정 4
paymethod "Card" 고정 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
url 가맹점 URL 50
moid 가맹점주문번호 40
goodName 상품명 80
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
price 결제금액 10
regNo 생년월일(YYMMDD)ENC 6
cardPw 카드비밀번호 2자리ENC 2
currency 통화코드 (WON / USD) 3
billKey 승인요청할 빌링키값 40
authentification 본인인증 여부, "00" 고정 2
cardQuota 할부기간(일시불 : 00 / 그 외 : 02, 03 ...) 2
quotaInterest 무이자구분 1
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+moid+price+billKey)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
payDate 결제일자 8
payTime 결제시간 6
tid 결제승인TID 40
prtcCode 부분취소가능여부 1
price 결제금액 10

비인증 결제

비인증 승인 연동에 대해 설명합니다.

* 해당 API는 비인증 방식으로 영업담당자를 통해 별도 계약 후 사용가능합니다.
POST /api/v1/formpay HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8

신용카드 (비인증)

* 해당 API는 비인증 방식으로, 로그인 후 확인 가능합니다.

가상계좌 (채번)

<<요청 파라미터>>
설명 SIZE 필수
type "Pay" 고정 3
paymethod "Vacct" 고정 5
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
moid 가맹점주문번호 40
url 가맹점 URL 50
goodName 상품명 80
price 결제금액 12
currency 통화코드(WON/USD) 3
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
bankCode 은행코드 2
dtInput 입금예정일자(YYYYMMDD) 8
tmInput 입금예정시간(HHMM) 4
nmInput 입금자명 20
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+moid+price)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid 채번TID 40
authDate 승인일자 8
authTime 승인시간 6
vacct 가상계좌번호 16
vacctName 예금주명
vacctBankCode 가상계좌 은행코드 2
validDate 가상계좌 입금예정날짜 2
validTime 가상계좌 입금예정시간 2
price 결제금액 12
price 결제금액 12

현금영수증

현금영수증 발급을 위한 요청/응답에 대해 설명합니다.

POST /api/v1/receipt HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
<<요청 파라미터>>
설명 SIZE 필수
type "Issue" 고정 5
paymethod "Receipt" 고정 7
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 상점에 발급된 가맹점 ID 10
goodName 상품명 80
currency 통화코드 3
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
crPrice 결제금액 10
supPrice 공급가액 10
tax 부가세 10
srcvPrice 봉사료 10
regNum 현금영수증 식별번호(주민번호,휴대폰번호,사업자번호)ENC 13
useOpt 현금영수증 발행용도(0:소득공제용, 1:지출증빙) 1
compayNumber 서브몰사업자번호 10
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+crPrice+supPrice+srcvPrice+regNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid 현금영수증발급 TID 40
authDate 발급일자 8
authTime 발급시간 6
authCode 현금영수증 발급결과코드 40
authNo 현금영수증 승인번호
authPrice 현금영수증 금액 10
authSupplyPrice 공급가액 10
authTax 부가세 10
authSrvcPrice 봉사료 10
authUseOpt 현금영수증 발행구분(0:소득공제, 1:지출증빙) 1

포인트

OCB적립에 대해 설명합니다.

POST /api/v1/point HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
<<요청 파라미터>>
설명 SIZE 필수
type "Point" 고정 5
paymethod "OCBPoint" 고정 8
payOption OCB구분 10 OCBplus
mid 상점에 발급된 가맹점 ID 10
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
url 상점URL
clientIp 요청 서버IP 15
goodName 상품명 80
currency 통화코드 3
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
price 결제금액 10
savePrice 적립금액 10
ocbNum OCB 카드번호ENC 16
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+price+savePrice+ocbNum)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
paymethod 지불수단 10
tid OCB 적립TID 40
confirmSavePrice OCB적립 금액 10
confirmSavePoint OCB적립 포인트 10

기타요청전문

기타 PG 거래에 대한 내용을 설명합니다.

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

수동매입

<<요청 파라미터>>
설명 SIZE 필수
type "Extra" 고정 5
paymethod "Capture" 고정 7
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 상점에 발급된 가맹점 ID 10
originalTid 원거래번호 40
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+originalTid)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid TID 40

거래조회

<<요청 파라미터>>
설명 SIZE 필수
type "Extra" 고정 5
paymethod "Inquiry" 고정 7
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 상점에 발급된 가맹점 ID 10
originalTid 원거래번호 40
oid 주문번호 80
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid TID 40
price 결제금액 40
status 거래상태
(0 : 승인, 1 : 취소, 9 : 거래없음)
* 가상계좌 거래 – N : 입금대기, Y : 입금완료, C : 입금 전 취소
40
paymethod 지불수단(해외결제시) 10
oid 상점 주문번호(해외결제시) 80
applNum 승인번호(해외결제시) 40
priceExchange 원화승인금액(해외결제시) 40
rtExchange 환율(해외결제시,은련카드 제외) 40
applDate 승인일자(해외결제시) 40
applTime 승인시간(해외결제시) 40

부분환불 가능여부 조회

<<요청 파라미터>>
설명 SIZE 필수
type "Extra" 고정 5
paymethod "RepayChk" 고정 8
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 상점에 발급된 가맹점 ID 10
originalTid 원거래번호 40
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+originalTid)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid TID 40
prtcCheckRemains 40
prtcCheckCnt 40
partCheckCode 40

에스크로

에스크로 거래에 대한 내용을 설명합니다.

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

배송등록

<<요청 파라미터>>
설명 SIZE 필수
type "Dlv" 고정 3
mid 가맹점 ID 10
clientIp 요청 서버IP 15
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
tid 에스크로 등록 요청 TID 40
oid 주문번호 40
report 에스크로 등록형태 (등록 : I / 변경 : U) 1
invoice 운송장번호
registName 배송등록자
exCode 택배사코드
exName 택배사명
charge 배송비 지급형태 (판매자부담 : SH / 구매자부담 : BH) 2
invoiceDay 배송등록 확인일자
sendName 송신자 이름
sendPost 송신자 우편번호
sendAddr1 송신자 주소 1
sendAddr2 송신자 주소 2 o
sendTel 송신자 전화번호
recvName 수신자 이름
recvPost 수신자 우편번호(구분자 없이)
recvAddr 수신자 주소 1
recvTel 수신자 전화번호
goodsCode 상품코드 o
goods 상품명 o
goodsCnt 상품수량 o
price 가격
hashData 전문위변조 HASHHASH
hash(KEY+type+timestamp+clientIp+mid+oid+tid+price)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
resultDate 처리 일자 8
resultTime 처리 시각 6

구매거절 확인

<<요청 파라미터>>
설명 SIZE 필수
type "Dncf" 고정 4
mid 가맹점 ID 10
clientIp 요청 서버IP 15
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
originalTid 에스크로 거절 확인 TID 40
dcnfName 거절 확인 처리자
hashData 전문위변조 HASHHASH
hash(KEY+type+timestamp+clientIp+mid+originalTid)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
dcnfDate 처리 일자 8
dcnfTime 처리 시각 6

지불수단코드

지불수단 코드 지불수단 코드
신용카드 Card 계좌이체 Acct
가상계좌 Vacct 휴대폰 HPP
가상계좌 채번취소 GVacct (채번취소 시 사용) 현금영수증 Receipt
페이팔 Paypal