서비스 소개
노티(웹훅) 서비스는 거래의 상태가 변경되었을 때 가맹점에서 실시간으로 통지를 받을 수 있도록 제공되는 서비스 입니다.
단, 거래거절 건에 대해서는 통지를 하지 않고 정상 처리된 거래만 통지가 됩니다.
노티 서비스는 HTTP POST 메소드로 전달되며, HTTP 통신도 지원하고 있지만 보안강화를 위해 HTTPS 통신을 권장합니다.
노티 URL 및 통지 받을 서비스 등록은 영업담당자를 통해 등록요청을 하셔야 됩니다.
노티 수신 후 응답 처리
노티 수신 후 응답처리 관련 하여 아래와 같이 처리해주시기 바랍니다.
노티 정상 수신 했을 경우: {"resCd":"0000","resMsg":"Success"}
노티 수신 후 DB처리 실패 등의 사유로 재수신 해야 할 경우: {"resCd":"5001","resMsg":"FAIL"}
노티(웹훅) 재전송 정책
노티 전송 후 응답으로 정상으로 응답할 경우 더 이상 전송하지 않습니다. 최초 노티전송이 실패하면 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에서 부여한 상점ID |
| notiType | String | 2 Byte | 필수 | 노티구분 노티구분 코드표 참조 |
| pgCno | String | 20 Byte | 필수 | PG거래번호 단, 가상계좌 입금통보 시 입금거래번호 |
| shopOrderNo | String | 40 Byte | 필수 | 상점 주문번호 |
노티 파라미터
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| amount | String | 12 Byte | 총 결제금액 | |
| remainAmount | String | 12 Byte | 캐시잔액 | |
| approvalNo | String | 20 Byte | 승인번호 | |
| transactionDate | String | 14 Byte | 거래일시(승인/취소/환불) | |
| pointAuthNo | String | 15 Byte | 포인트 승인번호 | |
| pointTransactionDate | String | 14 Byte | 포인트 승인일시 | |
| cardNo | String | 40 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" |
|
| bankCode | String | 3 Byte | 은행코드 | |
| bankName | String | 20 Byte | 은행명 | |
| accountNo | String | 20 Byte | 계좌번호 | |
| depositName | String | 20 Byte | 입금자명 | |
| expiryDate | String | 14 Byte | 계좌사용만료일 | |
| cashUsed | String | 1 Byte | 현금영수증 발행여부 (1:발급, 0:미발급) |
|
| cashResCd | String | 4 Byte | 현금영수증 결과코드 | |
| cashResMsg | String | 64 Byte | 현금영수증 결과메시지 | |
| cashAuthNo | String | 20 Byte | 현금영수증 승인번호 | |
| cashTranDate | String | 14 Byte | 현금영수증 처리일시 | |
| cashIssueType | String | 2 Byte | 현금영수증 발행용도 | |
| cashAuthType | String | 1 Byte | 현금영수증 인증수단 구분 | |
| cashAuthValue | String | 20 Byte | 현금영수증 인증 식별번호 | |
| cashAmount | String | 12 Byte | 현금영수증 금액 | |
| cashTaxAmount | String | 12 Byte | 현금영수증 과세 승인 금액 | |
| cashFreeAmount | String | 12 Byte | 현금영수증 비과세 승인 금액 | |
| cashVatAmount | String | 12 Byte | 현금영수증 부가세 금액 | |
| authId | String | 20 Byte | Phone ID | |
| billId | String | 20 Byte | 인증번호 | |
| mobileNo | String | 20 Byte | 휴대폰 번호 | |
| mobileAnsimUsed | String | 1 Byte | 안심결제 사용유무 | |
| cpCode | String | 4 Byte | 서비스사 코드 | |
| pntAmount | String | 9 Byte | 사용포인트 | |
| remainPoint | String | 9 Byte | 잔여한도 | |
| payPnt | String | 9 Byte | 할인/발생포인트 | |
| accruePnt | String | 9 Byte | 누적포인트 | |
| deductPnt | String | 9 Byte | 총차감 포인트 | |
| paybackPnt | String | 9 Byte | payback 포인트 | |
| mallName | String | 20 Byte | 가맹점명 | |
| escrowUsed | String | 1 Byte | 에스크로 여부 | |
| escrowTypeCode | String | 1 Byte | 에스크로 종류("K") | |
| complexUsed | String | 1 Byte | 복합결제 유무 | |
| cancelAcqDate | String | 14 Byte | 취소거래일시 | |
| joinNo | String | 15 Byte | 가맹점 번호 | |
| statusCode | String | 4 Byte | 거래상태 코드 참조코드표 참조 |
|
| statusMessage | String | 100 Byte | 거래상태메시지 | |
| vanTid | String | 15 Byte | VAN TID | |
| vanSno | String | 12 Byte | VAN거래일련번호 | |
| payMethodTypeCode | String | 4 Byte | 결제수단 코드 참조코드표 참조 |
|
| notiType | String | 2 Byte | 노티타입 | |
| tlfSno | String | 20 Byte | 가상계좌 채번거래번호 | |
| certNo | String | 20 Byte | ARS 인증거래번호 | |
| partCancelUsed | String | 1 Byte | 부분취소 가능여부 | |
| membGubun | String | 1 Byte | 가맹점 구분 | |
| cardGubun | String | 1 Byte | 카드 종류(신용/체크/기프트) | |
| cardClass | String | 1 Byte | 임직원카드 구분 | |
| cardBizGubun | String | 1 Byte | 카드 구분(개인/법인) | |
| couponFlag | String | 1 Byte | 쿠폰/즉시할인 사용유무 | |
| cponAuthNo | String | 20 Byte | 쿠폰 승인번호 | |
| cponTranDate | String | 14 Byte | 쿠폰 승인일시 | |
| remainCpon | String | 9 Byte | 쿠폰 잔액 | |
| couponAmount | String | 9 Byte | 쿠폰/즉시할인 사용금액 | |
| cancelAmount | Number | 부분취소(환불)금액 | ||
| cancelCardAmount | Number | 신용카드 취소금액 (즉시할인 시) | ||
| cancelCouponAmount | Number | 쿠폰 취소금액 (즉시할인 시) | ||
| cancelPgCno | String | 20 Byte | 취소(환불)거래번호 | |
| cardnoHash | String | 44 Byte | 카드번호 해시 값 | |
| vcntType | String | 1 Byte | 가상계좌 종류 | |
| customerName | String | 20 Byte | 고객명 | |
| vpCardcode | String | 15 Byte | VP카드코드 | |
| taxFlg | String | 4 Byte | 복합과세 Flag("TG01") | |
| taxAmount | String | 12 Byte | 과세 금액(복합과세 사용 시) | |
| freeAmount | String | 12 Byte | 비과세 금액(복합과세 사용 시) | |
| vatAmount | String | 12 Byte | 부가세 금액(복합과세 사용 시) | |
| cponTerms | String | 12 Byte | 할인기준금액 | |
| cancelRemainAmount | String | 12 Byte | 취소 후 잔액 | |
| shopValue1 | String | 1000 Byte | 가맹점 여유필드1 | |
| shopValue2 | String | 100 Byte | 가맹점 여유필드2 | |
| shopValue3 | String | 100 Byte | 가맹점 여유필드3 | |
| shopValue4 | String | 100 Byte | 가맹점 여유필드4 | |
| shopValue5 | String | 100 Byte | 가맹점 여유필드5 | |
| shopValue6 | String | 100 Byte | 가맹점 여유필드6 | |
| customerId | String | 20 Byte | 고객ID | |
| cardAmount | String | 12 Byte | 신용카드 승인금액 | |
| cancelPointAmount | String | 12 Byte | 포인트 취소금액 | |
| depositPgCno | String | 20 Byte | (환불) 가상계좌 입금거래번호 | |
| depoBkcd | String | 3 Byte | 입금자 은행코드 | |
| depoBknm | String | 20 Byte | 입금자 은행명 | |
| dayRemPnt | String | 9 Byte | 일 잔여 포인트 | |
| monthRemPnt | String | 9 Byte | 월 잔여 포인트 | |
| dayRemCnt | String | 9 Byte | 일 잔여한도 횟수 | |
| multiCardAmount | String | 12 Byte | 복합결제 신용카드 승인/취소 금액 | |
| multiPntAmount | String | 12 Byte | 복합결제 포인트 승인/취소 금액 | |
| multiCponAmount | String | 12 Byte | 복합결제 쿠폰 승인/취소 금액 | |
| subCardCd | String | 3 Byte | 서브 카드코드 | |
| cardMaskNo | String | 40 Byte | 마스킹된 카드번호 | |
| oilMgrCost | String | 9 Byte | 주유 단가 | |
| oilMgrVolume | String | 9 Byte | 주유 유량 | |
| oilPayType | String | 1 Byte | 주유선결제 복합결제수단 | |
| mobileCd | String | 3 Byte | 이통사코드 | |
| basketUsed | String | 1 Byte | 장바구니(다중정산) 결제여부 | |
| basketUsed | String | 1 Byte | 장바구니(다중정산) 결제여부 | |
| bkResCnt | String | 2 Byte | 장바구니 상품 개수(최대 20개) | |
| productNo[1-20] | String | 40 Byte | 개별상품 주문번호 | |
| productPgCno[1-20] | String | 20 Byte | 개별상품 PG거래번호 | |
| sellerId[1-20] | String | 40 Byte | 판매자 ID |
승인노티(notiType=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",
"cardGubun": "N",
"cardBizGubun": "P",
"couponFlag": "N",
"cardnoHash": "Gy8kMh3KAAAAAT0G9u74AAAAAIUXqVcMmPy0UWAAAAA",
"customerName": "홍길동",
"customerId": "test",
// ...
}
변경노티(notiType=20) : 일반결제 취소거래 전송
일반 결제 승인 취소, 실시간 환불 거래 통지 합니다.
결제 취소(환불 포함)응답 항목과 동일합니다
{
"resCd": "0000",
"resMsg": "정상취소",
"pgCno": "25110509270000000000",
"shopOrderNo": "PGSAMPLE_202511051762302000000",
"amount": "44792",
"transactionDate": "20251105092752",
"remainPoint": "0",
"accruePnt": "0",
"escrowUsed": "N",
"cancelDate": "20251105092752",
"statusCode": "TS02",
"statusMessage": "승인취소",
"payMethodTypeCode": "11",
"mallId": "T0001997",
"notiType": "20",
"cancelAmount": "44792",
"cancelCardAmount": "44792",
"cancelCouponAmount": "0",
"cancelPgCno": "25110509270000000000",
"mgr_req_msg": "단순 변심",
"dayRemPnt": "0",
"monthRemPnt": "0",
"dayRemCnt": "0",
"basketUsed": "N"
}
}
입금노티(notiType=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": "카카오뱅크",
// ...
}
입금취소노티(notiType=31) : 일반 가상계좌 입금취소 전송
가상계좌 입금 취소 내역을 전달합니다.
입금취소는 입금이 완료된 이후, 대외기관(은행)의 내부 시스템 오류로 입금이 취소된 상태(고객계좌로 반환된 상태.)를 말합니다.
은행 직권으로 자동취소된 거래로, 일반적인 환불/취소 절차와는 다른 경우입니다.
※ 주의사항 ※
✔ 가상계좌 서비스를 이용하는 경우 반드시 해당 노티(웹훅) 이벤트를 등록하여 주시기 바랍니다.
{
"resCd": "0000",
"resMsg": "입금취소",
"pgCno": "25102315213310907332",
"mallId": "T0021116",
"amount": "1004",
"shopOrderNo": "PGSAMPLE_202510231761200487932",
"notiType": "31",
"transactionDate": "20251023153126",
"bankCode": "20",
"bankName": "우리은행",
"accountNo": "T1619272118508",
"depositName": "test",
"escrowUsed": "Y",
"payMethodTypeCode": "22",
"statusCode": "",
"statusMessage": "",
"tlfSno": "25102315213310907332",
"accountType": "V",
"customerId": "USER_1761200487932",
"customerName": "TESTER",
"depoBkcd": "020",
"depoBknm": "우리은행"
[생략]
}
에스크로노티(notiType=40) : 에스크로 입금, 환불완료, 구매확인, 구매거절 거래 전송
에스크로 서비스를 통해 거래상태(입금, 환불완료, 구매확정, 구매거절)변경된 정보를 통지합니다.
{
"resCd": "0000",
"resMsg": "입금완료",
"pgCno": "25110509270000000000",
"mallId": "T0001997",
"amount": "50000",
"shopOrderNo": "PGSAMPLE_202511051762302000000",
"notiType": "40",
"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": "25110312240000000000",
"accountType": "V",
"customerId": "USER_1760669794164",
"customerName": "홍길동",
"depoBkcd": "020",
"depoBknm": "우리은행",
[생략]
}
환불노티(notiType=50) : 지결환불 완료 거래 전송
지결 환불의 완료 거래정보를 통지 합니다.
{
"resCd": "0000",
"resMsg": "정상처리",
"mallId": "T0001997",
"pgCno": "25110509270000000000",
"shopOrderNo": "PGSAMPLE_202511051762302000000",
"transactionDate": "20251105092752",
"escrowUsed": "N",
"statusCode": "RF02",
"statusMessage": "환불완료",
"payMethodTypeCode": "22",
"mallId": "T0001997",
"notiType": "50",
"cancelPgCno": " 25103110000000",
"mgr_req_msg": "환불",
"depositgPgCno": "25110509270000000000",
"basketUsed": "N"
}
이체불능노티(notiType=51) : 즉시환불 시 이체불능 거래 전송
이체불능은 대외기관(은행)으로부터 환불 거절 받은 상태를 말합니다.
환불 거절 상태이므로 즉시환불 재요청이 필요합니다.
※ 주의사항 ※
✔ 해당 이벤트를 받을 경우 반드시 실시간 환불 또는 지급지시를 통해 재요청을 해야 합니다.
{
"resCd": "5413",
"resMsg": "기타수취불가",
"notiType": "51",
"mallId": "T0001997",
"pgCno": "21032609005610816914",
"shopOrderNo": "20210326090046",
"bankCode": "004",
"bankName": "국민은행",
"accountNo": "11002235458445"
}
은련결제노티(notiType=70) : 은련카드 결제완료 거래 전송
은련카드 특성 상 노티 수신 시 최종 결제 확인 처리가 필요합니다.
노티 정상 수신 응답을 주셔야 승인이 완료됩니다.
{
"resCd": "0000",
"resMsg": "정상",
"notiType": "70",
"payMethodTypeCode": "11",
"pgCno": "25110509270000000000",
"mallId": "T0001997",
"shopOrderNo": "PGSAMPLE_202511051762302000000",
"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"
}
노티(웹훅) 구분 코드
| 코드 | 결제수단 | 설명 |
|---|---|---|
| 10 | 승인 | 신용카드, 계좌이체, 휴대폰 등 결제처리 정상승인 거래 통지 |
| 20 | 변경 | 일반결제에서 취소, 환불 정상처리 거래 통지 |
| 30 | 입금 | 가상계좌 입금거래 통지 |
| 31 | 입금취소 | 가상계좌 입금통지 후 금융기관 오류로 인한 취소통지 |
| 40 | 에스크로 | 에스크로 상태변경 거래 통지 |
| 50 | 환불완료 | 지결환불의 환불완료 거래 통지 |
| 51 | 이체불능 | 이체불능 거래 통지 |
| 70 | 은련결제 | 은련카드 결제확인 거래 통지(단, SMS pay는 예외) |