노티(웹훅) 서비스

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

주의사항

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

노티 서비스는 HTTP POST 메소드로 전달되며, HTTP 통신도 지원하고 있지만 보안강화를 위해 HTTPS 통신을 권장합니다.

노티 URL 및 통지 받을 서비스 등록은 가맹점 관리자를 통해 등록 가능합니다.

노티(웹훅) 재전송 정책

노티(웹훅) 전송 후 응답으로 정상으로 응답할 경우 더 이상 전송하지 않습니다. 최초 노티전송이 실패하면 3분 간격으로 최대 10회까지 재전송 합니다. 10회까지 노티(웹훅)가 실패된 거래는 가맹점 관리자>거래관리>노티조회 메뉴를 통해 재전송 요청을 하시면 처음부터 다시 재전송 됩니다.

전송 발생 주의 (Network Retry)

상점 서버에서 정상적으로 수신 처리를 완료했더라도, 일시적인 네트워크 불안정이나 타임아웃(Read Timeout)으로 인해 이지페이 서버가 상점의 응답을 받지 못할 수 있습니다.

이 경우 이지페이 서버는 전송 실패로 간주하고 동일한 결제 건에 대해 노티를 재전송합니다. 따라서 상점에서는 반드시 거래번호 중복 체크 로직을 구현하여 동일한 주문이 이중으로 처리되지 않도록 방어해야 합니다.

노티(웹훅) 응답 예시

{  
    // 결과처리 성공했을 경우
    "resCd": "0000",
    "resMsg": "정상"
    // 결과처리 실패했을 경우
    "resCd": "5001",
    "resMsg": "처리실패"
}

방화벽 정책

노티(웹훅) 서비스를 사용하는 상점의 경우 인바운드 트래픽에 대해 다음과 같이 상점 서버의 방화벽을 설정하시기 바랍니다.

구분	출발지IP	설명
운영	203.233.72.150	INBOUND
	203.233.72.151	INBOUND
	61.33.211.180	INBOUND
개발	61.33.205.151	INBOUND

노티(웹훅) 서비스 이벤트 목록

구분	이벤트명	설명
10	승인	신용카드, 계좌이체, 휴대폰 등 결제 정상승인 거래 통지
20	변경	결제 승인거래에 대한 취소, 환불 정상처리 거래 통지
30	입금	가상계좌 입금 거래 통지
31	입금취소	가상계좌 입금통지 후 금융기관 오류로 인하여 취소된 경우 통지
40	에스크로	에스크로 거래의 상태변경 통지
50	환불완료	지결환불 완료 거래 통지
51	이체불능	실시간 환불(지급지시 포함) 시 금융기관 오류로 인하여 환불이 불가능한 경우 통지
70	은련카드 결제	은련카드 결제확인 통지

연동하기

HTTP Header

상점에서 아래 헤더 정보를 처리할 수 있도록 해야 합니다.

헤더 정보

POST https://{상점 노티 URL}
Content-type: application/json; charset=utf-8

HTTP Body

공통 파라미터

필드명	타입	길이	필수여부	설명
resCd	String	4Byte	✅	응답코드
resMsg	String	1000Byte	✅	응답메시지
mallId	String	8Byte	✅	KICC에서 부여한 상점ID
notiType	String	2Byte	✅	노티구분 노티(웹훅) 서비스 이벤트 목록 참고
pgCno	String	20Byte	✅	PG 거래고유번호 단, 가상계좌 입금통보 시 입금거래번호
shopOrderNo	String	40Byte	✅	상점 주문번호

노티 파라미터

필드명	타입	길이	설명
amount	String	12byte	총 결제금액
approvalNo	String	20byte	승인번호
transactionDate	String	14byte	승인일시
pointAuthNo	String	15byte	포인트 승인번호
pointTransactionDate	String	14byte	포인트 승인일시
cardNo	String	40byte	카드번호
issuerCode	String	3byte	발급사 코드 카드사 코드 참고
issuerName	String	20byte	발급사명
acquirerCode	String	3byte	매입사코드 카드사 코드 참고
acquirerName	String	20byte	매입사명
installmentMonth	String	2byte	할부개월
freeInstallmentTypeCode	String	2byte	무이자 여부 유이자 거래 : "00" 상점 무이자 : "02" 카드사 무이자 : "03"
bankCode	String	3byte	은행코드
bankName	String	20byte	은행명
accountNo	String	20byte	계좌번호
depositName	String	10byte	입금자명
expiryDate	String	14byte	계좌사용만료일
cashUsed	String	1byte	현금영수증 발행여부 (1:발급, 0:미발급)
cashResCd	String	4byte	현금영수증 결과코드
cashResMsg	String	64byte	현금영수증 결과 메시지
cashAuthNo	String	20byte	현금영수증 승인번호
cashTranDate	String	14byte	현금영수증 승인일시
cashIssueType	String	2byte	현금영수증 발행용도
cashAuthType	String	1byte	현금영수증 인증구분
cashAuthValue	String	20byte	현금영수증 인증번호
cashAmount	String	12byte	현금영수증 금액
cashTaxAmount	String	12byte	현금영수증 과세 승인 금액
cashFreeAmount	String	12byte	현금영수증 비과세 승인 금액
cashVatAmount	String	12byte	현금영수증 부가세 금액
authId	String	20byte	PhoneID
billId	String	20byte	인증번호
mobileNo	String	20byte	휴대폰번호
mobileAnsimUsed	String	1byte	안심결제 사용유무
cpCode	String	4byte	서비스사 코드(간편결제, 포인트) (제휴 서비스사 코드 참고)
pntAmount	String	9byte	사용포인트
remainPoint	String	9byte	잔여한도
payPnt	String	9byte	할인/발생포인트
accruePnt	String	9byte	누적포인트
deductPnt	String	9byte	총차감 포인트
paybackPnt	String	9byte	payback 포인트
mallName	String	20byte	상점명
escrowUsed	String	1byte	에스크로 사용유무
escrowTypeCode	String	1byte	에스크로 종류("K")
complexUsed	String	1byte	복합결제 유무
cancelAcqDate	String	14byte	매입취소일시
cancelDate	String	14byte	취소일시
joinNo	String	15byte	상점 번호
statusCode	String	4byte	거래상태 코드 (거래상태 코드 참고)
statusMessage	String	100byte	상태메시지
vanTid	String	15byte	VAN TID
vanSno	String	12byte	VAN거래일련번호
payMethodTypeCode	String	2byte	결제수단 코드 (결제수단 코드 참고)
tlfSno	String	20byte	가상계좌 채번거래번호
certNo	String	20byte	ARS 인증거래번호
partCancelUsed	String	1byte	부분취소 가능여부
membGubun	String	1byte	상점 구분
cardGubun	String	1byte	카드 종류(신용/체크)
cardClass	String	1byte	임직원카드 구분
cardBizGubun	String	1byte	카드 구분(개인/법인)
couponFlag	String	1byte	쿠폰/즉시할인 사용유무
cponAuthNo	String	20byte	쿠폰승인번호
cponTranDate	String	14byte	쿠폰승인일시
remainCpon	String	9byte	쿠폰 잔액
couponAmount	String	9byte	쿠폰/즉시할인 사용금액
cancelAmount	String	12byte	부분취소/환불 금액
cancelCardAmount	String	12byte	신용카드 취소금액
cancelCouponAmount	String	12byte	쿠폰 취소금액
cancelPgCno	String	20byte	취소(환불) 거래고유번호
cardnoHash	String	44byte	카드번호 해시 값
vcntType	String	1byte	가상계좌 종류
customerName	String	20byte	고객명
vpCardcode	String	15byte	VP카드코드
taxFlg	String	4byte	복합과세 Flag("TG01")
taxAmount	String	12byte	과세 금액(복합과세 사용 시)
freeAmount	String	12byte	비과세 금액(복합과세 사용 시)
vatAmount	String	12byte	부가세 금액(복합과세 사용 시)
cponTerms	String	12byte	할인기준금액
cancelRemainAmount	String	12byte	취소 후 잔액
shopValue1	String	1000byte	상점여유필드1
shopValue2	String	100byte	상점여유필드2
shopValue3	String	100byte	상점여유필드3
shopValue4	String	100byte	상점여유필드4
shopValue5	String	100byte	상점여유필드5
shopValue6	String	100byte	상점여유필드6
customerId	String	20byte	고객ID
cardAmount	String	12byte	신용카드 승인금액
cancelPointAmount	String	12byte	포인트 취소금액
depositPgCno	String	20byte	(환불)가상계좌 입금거래번호
depoBkcd	String	3Byte	입금계좌 은행코드
depoBknm	String	20Byte	입금계좌 은행명
dayRemPnt	String	9byte	일 잔여 포인트
monthRemPnt	String	9byte	월 잔여 포인트
dayRemCnt	String	9byte	일 잔여한도 횟수
remainAmount	String	12byte	선불 취소 후 잔액
multiCardAmount	String	12byte	복합결제 신용카드 승인/취소 금액
multiPntAmount	String	12byte	복합결제 포인트 승인/취소 금액
multiCponAmount	String	12byte	복합결제 쿠폰 승인/취소 금액
subCardCd	String	3byte	서브 카드코드
cardMaskNo	String	40byte	마스킹된 카드번호
oilMgrCost	String	9byte	주유 단가
oilMgrVolume	String	9byte	주유 유량
oilPayType	String	1byte	주유 선결제 복합결제수단
mobileCd	String	3byte	이통사코드
basketUsed	String	1Byte	장바구니(다중정산) 결제여부
bkResCnt	String	2Byte	장바구니 상품 개수(최대 20개)
productNo[1-20]	String	40Byte	개별상품 주문번호
productPgCno[1-20]	String	20Byte	개별상품 PG 거래고유번호
sellerId[1-20]	String	40Byte	판매자 ID

승인 노티(10)

결제 수단별 결제 승인응답 항목과 동일합니다.

예시

{
  // 신용카드
  "resCd": "0000",
  "resMsg": "정상",
  "mallId": "{상점ID}",
  "notiType": "10",
  "pgCno": "{PG 거래고유번호}",
  "shopOrderNo": "{상점 주문번호}",
  "amount": "1200",
  "approvalNo": "01230000",
  "transactionDate": "20251105092752",
  "cardNo": "49000000****050*",
  "issuerCode": "027",
  "issuerName": "현대비자개인",
  "acquirerCode": "027",
  "acquirerName": "현대카드사",
  "freeInstallmentTypeCode": "00",
  "installmentMonth": "00",
  "pntAmount": "0",
  "escrowUsed": "N",
  "complexUsed": "N",
  "statusCode": "TS03",
  "statusMessage": "매입요청",
  "vanTid": "7574638",
  "vanSno": "807627429171",
  "payMethodTypeCode": "11",   
  "partCancelUsed": "Y",
  "membGubun": "2",
  "cardGubun": "N",
  "cardBizGubun": "P",
  "couponFlag": "N",
  "cardnoHash": "Gy8kMh3KAAAAAT0G9u74AAAAAIUXqVcMmPy0UWAAAAA",
  "customerName": "홍길동",
  "customerId": "test",
  "basketUsed": "N",
  // ...
}

변경 노티(20)

일반 결제 승인 취소, 실시간 환불 거래 통지 합니다. 결제 취소(환불 포함)응답 항목과 동일합니다.

예시

{
  "resCd": "0000",
  "resMsg": "정상취소",
  "mallId": "{상점ID}",
  "notiType": "20",
  "pgCno": "{원거래 PG 거래고유번호",
  "shopOrderNo": "{상점 주문번호}",
  "amount": "44792",
  "transactionDate": "20251105092752",
  "remainPoint": "0",
  "accruePnt": "0",
  "escrowUsed": "N",
  "cancelDate": "20251105092752",
  "statusCode": "TS02",
  "statusMessage": "승인취소",
  "payMethodTypeCode": "11",
  "cancelAmount": "44792",
  "cancelCardAmount": "44792",
  "cancelCouponAmount": "0",
  "cancelPgCno": "{취소(환불) 거래고유번호}",
  "dayRemPnt": "0",
  "monthRemPnt": "0",
  "dayRemCnt": "0",
  "basketUsed": "N",
  // ...
}

입금 노티(30)

가상계좌 입금 시 입금정보를 통지 합니다. 현금영수증 발행요청이 있는 경우 현금영수증 발행 결과도 전달 됩니다.

예시

{
  "resCd": "0000",
  "resMsg": "입금완료",
  "notiType": "30",
  "mallId": "{상점ID}",
  "pgCno": "{입금 거래번호}",    
  "amount": "15000",
  "shopOrderNo": "{상점 주문번호}",   
  "transactionDate": "20251105092752",
  "bankCode": "11",
  "bankName": "농협은행",
  "accountNo": "79013419904403",
  "depositName": "테스트",
  "escrowUsed": "N",
  "payMethodTypeCode": "22",
  "cashUsed": "1",
  "cashResCd": "0000",
  "cashResMsg": "정상",
  "cashTranDate": "20251105092752",
  "cashAuthNo": "128170000",
  "cashIssueType": "03",
  "cashAuthType": "3",
  "cashAuthValue": "0100001234",
  "statusCode": "",
  "statusMessage": "",
  "tlfSno": "{PG(채번) 거래번호}",
  "accountType": "V",
  "customerId": "",
  "customerName": "홍길동",
  "depoBkcd": "090",
  "depoBknm": "카카오뱅크",
  // ...
}

입금취소 노티(31)

가상계좌 입금취소 시 입금정보를 통지 합니다. 입금취소는 입금 완료 후 대외기관(은행)의 내부 시스템 오류로 인하여 대외기관 직권으로 취소된 거래 입니다.

주의사항

가상계좌 서비스를 이용하는 상점의 경우 반드시 해당 노티(웹훅) 이벤트를 등록하여 주시기 바랍니다.

예시

{
  "resCd": "0000",
  "resMsg": "입금취소",
  "notiType": "31",
  "mallId": "{상점ID}",
  "pgCno": "{입금 거래번호}",   
  "amount": "1004",
  "shopOrderNo": "{상점 주문번호}",   
  "transactionDate": "20251023153126",
  "bankCode": "20",
  "bankName": "우리은행",
  "accountNo": "T1619272118508",
  "depositName": "test",
  "escrowUsed": "Y",
  "payMethodTypeCode": "22",
  "statusCode": "",
  "statusMessage": "",
  "tlfSno": "PG(채번) 거래번호",
  "accountType": "V",
  "customerId": "USER_1761200487932",
  "customerName": "TESTER",
  "depoBkcd": "020",
  "depoBknm": "우리은행",
  // ...
}

에스크로 노티(40)

에스크로 거래로 거래상태(입금, 환불완료, 구매확정, 구매거절)가 변경되면 결과를 통지 합니다.

예시

{
  "resCd": "0000",
  "resMsg": "입금완료",
  "notiType": "40",
  "mallId": "{상점ID}",
  "pgCno": "입금 거래번호",   
  "amount": "50000",
  "shopOrderNo": "{상점 주문번호}",   
  "transactionDate": "20251105092752",
  "bankCode": "04",
  "bankName": "국민은행",
  "accountNo": "T9629078365992",
  "depositName": "테스트",
  "escrowUsed": "Y",
  "payMethodTypeCode": "22",
  "cashUsed": "1",
  "cashResCd": "0000",
  "cashResMsg": "정상",
  "cashTranDate": "20251105092752",
  "cashAuthNo": "588530253",
  "cashIssueType": "03",
  "cashAuthType": "3",
  "cashAuthValue": "0100001234",
  "statusCode": "ES04",
  "statusMessage": "입금완료",
  "tlfSno": "{PG(채번) 거래번호",
  "accountType": "V",
  "customerId": "USER_1760669794164",
  "customerName": "홍길동",
  "depoBkcd": "020",
  "depoBknm": "우리은행",
  // ...
}

환불완료 노티(50)

지결 환불의 완료 거래정보를 통지 합니다.

예시

{
  "resCd": "0000",
  "resMsg": "정상 처리",
  "notiType": "50",
  "mallId": "{상점ID}",
  "pgCno": "{원거래 PG 거래고유번호}", // 채번 거래번호
  "shopOrderNo": "{상점 주문번호}",
  "transactionDate": "20251105092752",
  "escrowUsed": "N",
  "statusCode": "RF02",
  "statusMessage": "환불완료",
  "payMethodTypeCode": "22",
  "cancelPgCno": "{취소(환불) 거래고유번호}",
  "depositPgCno": "{가상계좌 입금 거래번호}",
  "basketUsed": "N"
}

이체불능 노티(51)

실시간 환불(지급지시 포함) 시 금융기관 오류로 인하여 환불(출금)이 불가능한 거래정보를 통지 합니다.

주의사항

해당 노티(웹훅) 이벤트를 받을 경우 반드시 실시간 환불 또는 지급지시를 통해 재요청을 해야 합니다.

예시

{
  "resCd": "5413",
  "resMsg": "기타수취불가",
  "notiType": "51",
  "mallId": "{상점ID}",
  "pgCno": "{PG 거래고유번호}",
  "shopOrderNo": "{상점 주문번호}",
  "bankCode": "004",
  "bankName": "국민은행",
  "accountNo": "11002235458445"
}

은련카드 결제 노티(70)

은련카드 결제확인 통지 합니다.

예시

{
  "resCd": "0000",
  "resMsg": "정상",
  "notiType": "70",
  "mallId": "{상점ID}",
  "payMethodTypeCode": "11",
  "pgCno": "{PG 거래고유번호}",   
  "shopOrderNo": "{상점 주문번호}",
  "kvp_pgid": "TEST11",
  "issuerCode": "081",
  "amount": "50000"
}

다중정산 장바구니 결과 정보

장바구니 상품 등록개수(bkResCnt)에 따라 productNo, productPgCno, sellerId 값이 전달됩니다.

예시

{
  // ...
  "basketUsed": "Y",
  "bkResCnt": "3",
  "productNo1": "P2025102017609368949211",
  "sellerId1": "EBC100000",
  "productPgCno1": "25102014082410899694",
  "productNo2": "P2025102017609368949212",
  "sellerId2": "EBC100001",
  "productPgCno2": "25102014082410899695",
  "productNo3": "P2025102017609368949213",
  "sellerId3": "EBC100002",
  "productPgCno3": "25102014082410899696"
}