노티

01개요

서비스 소개

노티(웹훅) 서비스는 거래의 상태가 변경되었을 때 가맹점에서 실시간으로 통지를 받을 수 있도록 제공되는 서비스 입니다.

단, 거래거절 건에 대해서는 통지를 하지 않고 정상 처리된 거래만 통지가 됩니다.

노티 서비스는 HTTP POST 메소드로 전달되며, HTTP 통신도 지원하고 있지만 보안강화를 위해 HTTPS 통신을 권장합니다.
노티 URL 및 통지 받을 서비스 등록은 영업담당자를 통해 등록요청을 하셔야 됩니다.

노티(웹훅) 재전송 정책

노티 전송 후 응답으로 정상으로 응답할 경우 더 이상 전송하지 않습니다. 최초 노티전송이 실패하면 3분 간격으로 최대 10회까지 재전송 합니다.
10회까지 노티가 실패된 거래는 가맹점 관리자>거래관리>노티조회 메뉴를 통해 재전송 요청을 하시면 처음부터 다시 재전송 됩니다.
계속하여 노티 전송이 실패한다면 등록한 노티 URL의 포트에 대한 방화벽 설정이 허용되었는지 확인하여 주시기 바랍니다.

방화벽 설정

노티(웹훅) 서비스를 이용하기 위해서는 가맹점에서 아래 출발지 IP를 필히 허용해 주셔야 합니다.

구분 출발지 IP 설명
운영 203.233.72.150 INBOUND
203.233.72.151 INBOUND
61.33.211.180 INBOUND
테스트 61.33.205.151 INBOUND

02노티(웹훅) 연동하기

노티구분을 확인하고 상태가 변경된 거래 정보를 받아 변경상태를 처리하면 됩니다.

HTTP Header

항목 Desc 설명
Method POST
Content-type application/json
Charset utf-8

HTTP Body

공통 파라미터

필드명 타입 최대크기 필수여부 설명
resCd String 4 Byte 필수 응답코드
resMsg String 100 Byte 필수 응답메시지
mallId String 8 Byte 필수 KICC에서 부여한 상점IDs
notiType String 2 Byte 필수 노티구분
노티구분 코드표 참조
pgCno String 20 Byte 필수 PG거래번호

단, 가상계좌 입금통보 시 입금거래번호

shopOrderNo String 40 Byte 필수 상점 주문번호

노티 파라미터

필드명 타입 최대크기 필수여부 설명
statusCode String 4 Byte 필수 거래상태 코드
참조코드표 참조
statusMessage String 10 Byte 필수 거래상태 메시지
payMethodTypeCode String 2 Byte 필수 결제수단 코드
참조코드표 참조
amount Number 총 결제금액
transactionDate String 14 Byte 거래일시(승인/취소/환불)
approvalNo String 20 Byte 승인번호
cardNo String 20 Byte 마스킹된 카드번호
issuerCode String 3 Byte 발급사 코드
참조코드표 참조
issuerName String 20 Byte 발급사명
acquirerCode String 3 Byte 매입사 코드
참조코드표 참조
acquirerName String 20 Byte 매입사명
installmentMonth Number 할부개월
freeInstallmentTypeCode String 1 Byte 무이자 여부
유이자 거래 : "00"
가맹점 무이자 : "02"
카드사 무이자 : "03"
cardGubun String 1 Byte 카드 종류(신용/체크/기프트)
cardBizGubun String 1 Byte 카드 구분(개인/법인)
bankCode String 3 Byte 은행코드
bankName String 20 Byte 은행명
accountNo String 20 Byte 계좌번호
depositName String 20 Byte 예금주명
cashUsed String 1 Byte 현금영수증 발행여부
cashResCd String 4 Byte 현금영수증 처리결과 코드
cashResMsg String 100 Byte 현금영수증 처리결과 메시지
cashAuthNo String 20 Byte 현금영수증 승인번호
cashTranDate String 14 Byte 현금영수증 처리일시
cashIssueType String 2 Byte 현금영수증 발행용도
cashAuthType String 1 Byte 현금영수증 인증수단 구분
cashAuthValue String 20 Byte 현금영수증 인증 식별번호
tlfSno String 20 Byte 가상계좌 채번거래번호
cpCode String 10 Byte 결제사 구분(간편결제, 포인트)
escrowUsed String 1 Byte 에스크로 여부
escrowTypeCode String 1 Byte 에스크로 종류("K")
taxFlg String 1 Byte 복합과세 Flag("TG01")
taxAmount Number 과세 금액(복합과세 사용 시)
freeAmount Number 비과세 금액(복합과세 사용 시)
vatAmount Number 부가세 금액(복합과세 사용 시)
cancelPgCno String 20 Byte 취소거래번호(환불포함)
depositPgCno String 20 Byte 환불 입금거래번호
cancelAcqDate String 14 Byte 매입취소일시
cancelDate String 14 Byte 취소거래일시
refundDate String 14 Byte 환불거래일시
cancelAmount Number 취소금액(환불포함)
cancelCardAmount Number 신용카드 취소금액(즉시할인 시)
cancelCouponAmount Number 즉시할인 취소금액(즉시할인 시)
cancelRemainAmount Number 취소가능 잔액
customerName String 20 Byte 고객명
customerId String 20 Byte 고객ID
shopValue1 String 64 Byte 가맹점 여유필드1
shopValue2 String 64 Byte 가맹점 여유필드2
shopValue3 String 32 Byte 가맹점 여유필드3
shopValue4 String 32 Byte 가맹점 여유필드4
shopValue5 String 64 Byte 가맹점 여유필드5
shopValue6 String 64 Byte 가맹점 여유필드6
basketResList Array(Object) 장바구니 결과 List(다중정산)

장바구니 결과 List정보(basketResList)

필드명 타입 최대크기 필수여부 설명
productOid String 40 Byte 필수 개별상품 주문번호
productPgCno String 20 Byte 필수 개별상품 PG거래번호
sellerId String 40 Byte 필수 판매자 ID

승인노티(notiType=10) : 일반결제 승인거래 전송

결제수단별 노티 파라미터가 상이할 수 있으니, 파라미터 내용을 참조하여 주시기 바랍니다.

{

   "resCd": "0000",

   "resMsg": "MPI결제 정상",

   "notiType": "10",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "statusCode": "TS01"

   "statusMessage": "승인"

   [생략]

}

변경노티(notiType=20) : 일반결제 취소거래 전송

취소 API의 응답Body와 동일합니다. 현금영수증 발행이 있는 거래는 현금영수증 취소처리 결과도 전달됩니다.

{

   "resCd": "0000",

   "resMsg": "정상취소",

   "notiType": "20",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "statusCode": "TS02"

   "statusMessage": "승인취소"

   }

}

입금노티(notiType=30) : 일반 가상계좌 입금거래 전송

가상계좌 입금 시 입금내역을 전달합니다. 현금영수증 발행요청이 있는 거래의 경우 현금영수증 발행 결과도 전달됩니다.

{

   "resCd": "0000",

   "resMsg": "입금완료",

   "mallId": "T0001997",

   "notiType": "30",

   "pgCno": "21032609005610816914", // ※ 주의!! 입금 거래번호 입니다.

   "shopOrderNo": "20210326090046",

   "statusCode": "TS02"

   "statusMessage": "승인취소"

   "tlfSno" : "21032609005610811213", // 채번 거래번호

   [생략]

}

에스크로노티(notiType=40) : 에스크로 입금, 환불완료, 구매확인, 구매거절 거래 전송

에스크로 서비스에서 고객 또는 KICC에서 상태를 변경한 정보를 전달 합니다.

{

   "resCd": "0000",

   "resMsg": "정상처리",

   "notiType": "40",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "statusCode": "ES12"

   "statusMessage": "구매확정"

}

환불노티(notiType=50) : 지결환불 완료 거래 전송

환불 API의 응답Body와 동일합니다. 현금영수증 발행이 있는 거래는 현금영수증은 취소처리 결과도 전달됩니다.

{

   "resCd": "0000",

   "resMsg": "정상취소",

   "notiType": "50",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "statusCode": "RF02"

   "statusMessage": "환불완료"

   "depositgPgCno": "21032609005610816914"

   "refundDate": "20241011120001"

   [생략]

}

이체불능노티(notiType=51) : 즉시환불 시 이체불능 거래 전송

노티 수신 시 환불이 거절상태라 즉시환불을 재요청 하셔야 합니다.

{

   "resCd": "5413",

   "resMsg": "기타수취불가",

   "notiType": "51",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "bankCode": "004"

   "bankName": "국민은행"

   "accountNo": "11002235458445"

}

은련결제노티(notiType=70) : 은련카드 결제완료 거래 전송

노티 수신 시 최종 결제확인 처리를 하셔야 합니다.

{

   "resCd": "0000",

   "resMsg": "MPI결제 정상",

   "notiType": "70",

   "mallId": "T0001997",

   "pgCno": "21032609005610816914",

   "shopOrderNo": "20210326090046",

   "amount": "1004"

   "IssuerCode": "081"

}

03노티(웹훅) 구분 코드

노티(웹훅) 구분 코드

코드 결제수단 설명
10 승인 신용카드, 계좌이체, 휴대폰 등 결제처리 정상승인 거래 통지
20 변경 일반결제에서 취소, 환불 정상처리 거래 통지
30 입금 가상계좌 입금거래 통지
31 입금취소 가상계좌 입금통지 후 금융기관 오류로 인한 취소통지
40 에스크로 에스크로 상태변경 거래 통지
50 환불완료 지결환불의 환불완료 거래 통지
51 이체불능 이체불능 거래 통지
70 은련결제 은련카드 결제확인 거래 통지(단, SMS pay는 예외)