INIAPI 소개

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

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

방화벽정보

INIAPI 서비스 위해서는 아래 정보에 대해 방화벽 허용이 필요 합니다.
개발계에서는 테스트 MID(INIpayTest, INIBillTst)만 사용 가능합니다.
항목 내용
개발 환경 deviniapi.inicis.com
203.238.37.19
운영 환경 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==
 

암호화

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 "Card" 고정 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
tid 취소요청 TID 40
msg 취소요청사유 80
price 환불요청금액 10
confirmPrice 재승인요청금액 10
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+tid+price+confirmPrice)
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 "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)
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

빌링키 발급

<<요청 파라미터>>
설명 SIZE 필수
type "Auth" 고정 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
cardNumber 카드번호ENC 16
cardExpire 카드유효기간 (yymm)ENC 4
regNo 생년월일(yymmdd)ENC 6
cardPw 카드비밀번호 앞 2자리ENC 2
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+moid+price+cardNumber)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
payDate 결제일자 8
payTime 결제시간 6
billKey 빌링키 40
cardKind 카드종류(0 : 개인 / 1: 법인) 1
cardCode 카드코드 2
tid 결제승인TID 40
payAuthCode 결제인증코드
price 결제금액 11

빌링 승인

<<요청 파라미터>>
설명 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

신용카드 (비인증)

<<요청 파라미터>>
설명 SIZE 필수
type "Pay" 고정 3
paymethod "Card" 고정 4
timestamp 전문생성시간(YYYYMMDDhhmmss) 14
clientIp 요청 서버IP 15
mid 가맹점 ID 10
url 가맹점 URL 50
moid 가맹점주문번호 40
goodName 상품명 80
price 결제금액 12
currency 통화코드(WON/USD) 3
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
quotaInterest 무이자구분 1
cardQuota 할부기간(일시불 : 00 / 그 외 : 02, 03 ...) 2
cardNumber 카드번호ENC 16
cardExpire 카드유효기간(YYMM)ENC 4
regNo 생년월일(YYMMDD)/사업자번호ENC 6
cardPw 카드비밀번호 앞 2자리ENC 2
cardPoint 카드포인트 사용유무 2
language 언어설정(eng) 3
hashData 전문위변조 HASHHASH
hash(KEY+type+paymethod+timestamp+clientIp+mid+moid+price+cardNumber)
128
<<응답 파라미터>>
설명 SIZE 필수
resultCode 응답코드("00" 성공) 2
resultMsg 응답메시지 100
tid 결제승인TID 40
payDate 결제일자 8
payTime 결제시간 6
payAuthCode 결제인증코드
cardCode 카드코드 2
checkFlg 카드종류구분 12
payAuthQuota 할부기간 12
price 결제금액 11
prtcCode 부분환불 가능여부 5

가상계좌 (채번)

<<요청 파라미터>>
설명 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
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 상품명
currency 통화코드 3
buyerName 구매자명 80
buyerEmail 구매자이메일 60
buyerTel 구매자 연락처 40
crPrice 결제금액 10
supPrice 공급가액 10
tax 부가세 10
taxFree 면세 10
srcvPrice 봉사료 10
regNum 현금영수증 식별번호(주민번호,휴대폰번호,사업자번호) 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 상품명
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+originalTid)
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

지불수단코드

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