서비스 소개
노티(웹훅) 서비스는 거래의 상태가 변경되었을 때 가맹점에서 실시간으로 통지를 받을 수 있도록 제공되는 서비스 입니다.
단, 거래거절 건에 대해서는 통지를 하지 않고 정상 처리된 거래만 통지가 됩니다.
노티 서비스는 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 |
노티구분을 확인하고 상태가 변경된 거래 정보를 받아 변경상태를 처리하면 됩니다.
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"
}
노티(웹훅) 구분 코드
| 코드 | 결제수단 | 설명 |
|---|---|---|
| 10 | 승인 | 신용카드, 계좌이체, 휴대폰 등 결제처리 정상승인 거래 통지 |
| 20 | 변경 | 일반결제에서 취소, 환불 정상처리 거래 통지 |
| 30 | 입금 | 가상계좌 입금거래 통지 |
| 31 | 입금취소 | 가상계좌 입금통지 후 금융기관 오류로 인한 취소통지 |
| 40 | 에스크로 | 에스크로 상태변경 거래 통지 |
| 50 | 환불완료 | 지결환불의 환불완료 거래 통지 |
| 51 | 이체불능 | 이체불능 거래 통지 |
| 70 | 은련결제 | 은련카드 결제확인 거래 통지(단, SMS pay는 예외) |