INIAPI 소개
이니시스 결제의 승인/취소/부분취소 등을 사용하기 위한 API 입니다.
INIAPI는 보안을 위해 HTTPS를 사용하며, TLS v1.2만 지원합니다.
INIAPI는 보안을 위해 HTTPS를 사용하며, TLS v1.2만 지원합니다.
방화벽정보
INIAPI 서비스 위해서는 아래 정보에 대해 방화벽 허용이 필요합니다.
스테이징 환경에서는 테스트 MID(INIpayTest, INIBillTst)만 사용 가능합니다.
스테이징 환경에서는 테스트 MID(INIpayTest, INIBillTst)만 사용 가능합니다.
| 항목 | 내용 |
|---|---|
| 스테이징 환경 | stginiapi.inicis.com 118.129.210.153 |
| 운영 환경 | iniapi.inicis.com 118.129.210.166, 183.109.71.79 |
| PORT | 443 |
대칭키
INIAPI는 필드 암호화 및 전문 Hash를 위해 대칭키를 사용합니다
KEY와 IV는 상점관리자새 창에서 생성/조회 가능합니다.
KEY와 IV는 상점관리자새 창에서 생성/조회 가능합니다.
> 상점정보 > 계약정보 > 부가정보 > INIAPI Key
<<테스트MID 대칭키>>
KEY는 데이터 암호화 및 hash 생성에 사용되며, IV는 데이터 암호화에 사용됩니다
| MID | KEY | IV |
|---|---|---|
| INIpayTest | ItEQKi3rY7uvDS8l | HYb3yQ4f65QL89== |
| INIBillTst | rKnPljRn5m6J9Mzz | W2KLNKra6Wxc1P== |
| iniescrow0 | yERbIlJ3NhTeObsA | tOGDXbfoajk2DQ== |
암호화 ENC
INIAPI는 주요 데이터는 암호화하여 전송하며, 암호화 알고리즘은 AES(AES/CBC/PKCS5Padding)를 사용합니다.
1> AES암호화는 128-cbc 방식입니다.
2> INIAPI key 와 iv 를 사용합니다.
1> AES암호화는 128-cbc 방식입니다.
2> INIAPI key 와 iv 를 사용합니다.
* AES암호화 생성 확인
API 요청
각 파라미터는 key=value로 세팅하여 POST로 요청합니다.
Form data 세팅 후 API 통신 구간에서 전체 URLencode 하여 전송합니다.
hash 검증 HASH
INIAPI는 요청전문 위변조 확인을 위해 hash를 생성합니다.
hash 알고리즘은 SHA-512를 사용하며, hash에 필요한 PlainText는 각 API별로 상이합니다.
1> SHA-512 사용합니다.
2> INIAPI key 를 사용합니다.
hash 알고리즘은 SHA-512를 사용하며, hash에 필요한 PlainText는 각 API별로 상이합니다.
1> SHA-512 사용합니다.
2> INIAPI key 를 사용합니다.
* hash암호화 생성 확인
API 목록
취소/환불
이니시스 거래에 대한취소/환불 및 부분취소/부분환불에 대해 안내합니다.
취소/환불 API는 신용카드/계좌이체/휴대폰 거래와 가상계좌 거래를 구분하여 처리합니다.
다만, 계좌이체와 휴대폰 거래의 환불은 거래특성상 "환불받을 계좌"가 필요한 경우가 있어 별도로 안내합니다.
다만, 계좌이체와 휴대폰 거래의 환불은 거래특성상 "환불받을 계좌"가 필요한 경우가 있어 별도로 안내합니다.
POST /api/v1/refund 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/refund
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/refund
결제/승인 취소
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| cancelDate | 취소일자 | 8 | ○ |
| cancelTime | 취소시간 | 6 | ○ |
결제/승인 부분취소
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | 설명 | Byte | Require |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| prtcTid | 원거래번호 | 40 | ○ |
| tid | 부분환불TID | 40 | ○ |
| prtcPrice | 취소 금액 | 12 | ○ |
| prtcRemains | 재승인금액 | 12 | ○ |
| prtcCnt | 부분환불 요청 횟수 | 2 | ○ |
| prtcType | 부분환불 구분 (0: 재승인방식, 1: 부분취소) | 2 | ○ |
계좌이체 환불
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| cancelDate | 취소일자 | 8 | ○ |
| cancelTime | 취소시간 | 6 | ○ |
| cshrCancelNum | 현금영수증 취소번호 | 10 | ○ |
계좌이체 부분환불
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | 설명 | Byte | Require |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| cancelDate | 취소일자 | 8 | ○ |
| cancelTime | 취소시간 | 6 | ○ |
| prtcTid | 원거래번호 | 40 | ○ |
| tid | 부분환불TID | 40 | ○ |
| prtcPrice | 취소 금액 | 12 | ○ |
| prtcRemains | 재승인금액 | 12 | ○ |
| prtcCnt | 부분환불 요청 횟수 | 2 | ○ |
가상계좌 환불
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| cancelDate | 취소일자 | 8 | ○ |
| cancelTime | 취소시간 | 6 | ○ |
| prtcTid | 원거래번호 | 40 | ○ |
| tid | 부분환불TID | 40 | ○ |
| prtcPrice | 취소 금액 | 12 | ○ |
| prtcRemains | 재승인금액 | 12 | ○ |
| prtcCnt | 부분환불 요청 횟수 | 2 | ○ |
가상계좌 부분환불
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| cancelDate | 취소일자 | 8 | ○ |
| cancelTime | 취소시간 | 6 | ○ |
| prtcTid | 원거래번호 | 40 | ○ |
| tid | 부분환불TID | 40 | ○ |
| prtcPrice | 취소 금액 | 12 | ○ |
| prtcRemains | 재승인금액 | 12 | ○ |
| prtcCnt | 부분환불 요청 횟수 | 2 | ○ |
휴대폰 환불
* 휴대폰 익월환불은 영업담당자를 통해 별도 계약 후 사용가능합니다.
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 URL: https://iniapi.inicis.com/api/v1/billing
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/billing
빌링키 발급
* 해당 API는 비인증 방식으로, 로그인 후 확인 가능합니다.
빌링 승인
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| type | "Billing" 고정 | 4 | ● |
| paymethod | 지불수단 코드(카드, 휴대폰)info | ● | |
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| payAuthCode | 승인번호 | ○ | |
| payDate | 결제일자 | 8 | ○ |
| payTime | 결제시간 | 6 | ○ |
| tid | 결제승인TID | 40 | ○ |
| prtcCode | 부분환불 가능여부(1 - 가능 / 0 - 불가능) | 1 | ○ |
| price | 결제금액 | 10 | ○ |
| cardCode | 카드코드 | 2 | ○ |
비인증 결제
비인증 승인 연동에 대해 설명합니다.
* 해당 API는 비인증 방식으로 영업담당자를 통해 별도 계약 후 사용가능합니다.
POST /api/v1/formpay 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/formpay
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/formpay
신용카드 (비인증)
* 해당 API는 비인증 방식으로, 로그인 후 확인 가능합니다.
가상계좌 (채번)
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
| flgCash | 현금영수증 발행여부(0: 미발행, 1: 소득공제 발행, 2: 지출증빙) | 1 | ○ |
| cashRegNo | 현금영수증 발행정보(주민번호, 휴대폰번호, 사업장등록번호 등) ENC | ○ | |
| hashData | 전문위변조 HASHHASH hash(KEY+type+paymethod+timestamp+clientIp+mid+moid+price) | 128 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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
API URL: https://iniapi.inicis.com/api/v1/receipt
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/receipt
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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
API URL: https://iniapi.inicis.com/api/v1/point
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/point
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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
API URL: https://iniapi.inicis.com/api/v1/extra
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/extra
수동매입
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| tid | TID | 40 | ○ |
거래조회
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ○ |
부분환불 가능여부 조회
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| tid | TID | 40 | ○ |
| prtcCheckRemains | 40 | ○ | |
| prtcCheckCnt | 40 | ○ | |
| partCheckCode | 40 | ○ |
에스크로
에스크로 결제와 구매결정은 INIpay Standard(PC) 모듈새 창과 INIpay Mobile 모듈새 창로 진행되어야 합니다.
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
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
API URL: https://iniapi.inicis.com/api/v1/escrow
배송등록
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| type | "Dlv" 고정 | 3 | ● |
| mid | 가맹점 ID | 10 | ● |
| clientIp | 요청 서버IP | 15 | ● |
| timestamp | 전문생성시간(YYYYMMDDhhmmss) | 14 | ● |
| tid | 에스크로 등록 요청 TID | 40 | ● |
| oid | 주문번호 | 40 | ● |
| report | 에스크로 등록형태 (등록 : I / 변경 : U) | 1 | ● |
| invoice | 운송장번호 | ● | |
| registName | 배송등록자 | ● | |
| exCode | 택배사코드info | ● | |
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| resultDate | 처리 일자 | 8 | ○ |
| resultTime | 처리 시각 | 6 | ○ |
구매거절 확인
<<요청 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| 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 | ● |
<<응답 파라미터>>
| 키 | 설명 | Byte | 필수 |
|---|---|---|---|
| resultCode | 응답코드("00" 성공) | 2 | ● |
| resultMsg | 응답메시지 | 100 | ● |
| dcnfDate | 처리 일자 | 8 | ○ |
| dcnfTime | 처리 시각 | 6 | ○ |
에스크로 상태 변경 노티 수신
노티발송(이니시스 -> 가맹점)
| 필드 | 필드명 | 필드사이즈 | 설명 | 비고 |
|---|---|---|---|---|
| id_merchant | 상점아이디 | 10 | P_MID로 전달한 값 | |
| no_oid | 주문번호 | 40 | 가맹점 주문번호 | |
| no_tid | 거래번호 | 40 | 이니시스 제공 TID | |
| cl_status | 에스크로 상태 | 2 | 에스크로 상태구분 | 배송등록(2),구매확인(3),자동구매확인(31),강제구매확인(32),구매거절(4),거래취소(8),거절확인(10) |
| dt_req | 요청일자 | 14 | YYYYMMDDhhmmss | |
| cl_paymethod | 결제수단 | 2 | 에스크로 원 결제수단 | 신용카드(0),ISP(1),계좌이체(16),가상계좌(17) |
| msg_deny | 구매 거절 사유 | 256 | 구매 거절 했을 경우 사유 | |
| price | 거래금액 | 12 | 거래금액 | |
| tid_org | 원거래 거래번호 | 40 | 부분 취소 시 원거래 거래번호 | 부분 취소 거래만 설정 |
노티응답(가맹점 -> 이니시스)
| 필드 | 필드명 | 필드사이즈 | 설명 | 비고 |
|---|---|---|---|---|
| cd_rslt | 결과코드 | 4 | 0000:정상처리,9999:처리실패 | 처리결과 |
| msg_rslt | 결과 메시지 | 1000 | 처리 실패시 해당 오류메시지 | 처리 결과 메시지 |
에스크로 주요 변경 시점(예>구매자가 이메일 상에서 구매결정(확정)을 완료 등)에 가맹점 측으로 해당 내역을 통보해주는 기능입니다. 상점 측에서는 정상 수신 여부를, 응답(NOTI CONFIRM)하여야 합니다. 해당 기능을 이용하려면 계약 담당자를 통해, 수신 받을 상점 측 URL 을 등록하여야 합니다
- 지불수단별, 승인 요청 시점의 주문번호를 기준으로 응답하며, 배송등록 시점에 사용되는 주문번호와 동일하게 설정을 권장합니다.
- 거래금액은 에스크로 상태에 따라 거래취소 시에는 취소금액, 그 외는 승인금액입니다.
- 원거래 TID 는 부분취소 거래만 설정됩니다.
- 지불수단별, 승인 요청 시점의 주문번호를 기준으로 응답하며, 배송등록 시점에 사용되는 주문번호와 동일하게 설정을 권장합니다.
- 거래금액은 에스크로 상태에 따라 거래취소 시에는 취소금액, 그 외는 승인금액입니다.
- 원거래 TID 는 부분취소 거래만 설정됩니다.
※ 유의사항
- 에스크로 노티는 10분 간격으로 일괄 전송되는 구조로 한 건의 거래가 10분 내 상태가 변경되면 여러 건의 노티(에스크로 상태별)가 전송 될 수 있습니다.
- 가맹점에서는 에스크로 노티 데이터를 히스토리로 관리하여 최종 에스크로 상태를 구분해야 합니다.
예시) - 매시간 X0분에 에스크로 노티 전송
1. 05분 : 에스크로 상태 '2' (배송등록)
2. 07분 : 에스크로 상태 변경 '3' (구매확인)
3. 10분 : 에스크로 노티 처리시 배송등록과 구매확인에 대한 노티 전문 모두 전송(한건의 거래에 2번의 노티 전송)
- 노티 전문은 먼저 등록 요청된 순으로 전송됩니다. (배송등록 → 구매확인)
- 에스크로 노티 응답 실패시 재전송처리는 10회 수행됩니다.
- 에스크로 노티는 10분 간격으로 일괄 전송되는 구조로 한 건의 거래가 10분 내 상태가 변경되면 여러 건의 노티(에스크로 상태별)가 전송 될 수 있습니다.
- 가맹점에서는 에스크로 노티 데이터를 히스토리로 관리하여 최종 에스크로 상태를 구분해야 합니다.
예시) - 매시간 X0분에 에스크로 노티 전송
1. 05분 : 에스크로 상태 '2' (배송등록)
2. 07분 : 에스크로 상태 변경 '3' (구매확인)
3. 10분 : 에스크로 노티 처리시 배송등록과 구매확인에 대한 노티 전문 모두 전송(한건의 거래에 2번의 노티 전송)
- 노티 전문은 먼저 등록 요청된 순으로 전송됩니다. (배송등록 → 구매확인)
- 에스크로 노티 응답 실패시 재전송처리는 10회 수행됩니다.
지불수단코드
| 지불수단 | 코드 | 지불수단 | 코드 |
|---|---|---|---|
| 신용카드 | Card | 계좌이체 | Acct |
| 가상계좌 | Vacct | 휴대폰 | HPP |
| 가상계좌 채번취소 | GVacct (채번취소 시 사용) | 현금영수증 | Receipt |
| 페이팔 | Paypal | 상품권 | Voucher |