웹훅(Webhook) API

해당 페이지는 NHN KCP의 가상계좌 서비스와 에스크로 서비스에서 발생하는 상태 변경 통보와 가맹점 처리 결과 응답에 대해 설명합니다.
가상계좌 서비스에서는 발급된 계좌의 입금·입금 취소 결과를, 에스크로 서비스에서는 구매확인·배송시작 등 거래 상태 변경 결과를 가맹점 Webhook URL로 전송합니다.
가맹점은 수신 데이터를 주문 정보와 매핑하여 DB 상태를 반영하고, 처리가 정상 완료된 경우 result 값을 0000으로 응답해야 합니다.
result 값이 없거나 0000이 아닌 경우 NHN KCP는 전송 실패로 처리하고 최대 10번까지 재전송합니다.

거래 상태 변경

Webhook 전송

가맹점 DB 처리

Responseresult=0000

요약

대상 서비스

가상계좌, 에스크로

HTTP Method

POST 방식으로 파라미터를 전송합니다.

정상 응답 기준

가맹점 DB 처리가 정상 완료된 경우 result 값으로 0000을 반환합니다.

재전송

result 값이 없거나 0000이 아닌 경우 일정 간격으로 최대 10번까지 재전송됩니다.

Webhook 발신 IP

테스트: 210.122.176.144
운영: 103.215.144.173, 103.215.144.174, 210.122.72.173

통보 유형

공통 파라미터의 tx_cd로 통보 업무를 구분합니다.

tx_cd	통보 유형	대상 서비스
TX00	가상계좌 입금	가상계좌 / 에스크로
TX01	가상계좌 환불	에스크로
TX02	구매확인 / 구매취소	에스크로
TX03	배송시작	에스크로
TX04	정산보류	에스크로
TX05	즉시취소	에스크로
TX06	취소	에스크로
TX07	발급계좌해지	에스크로

요청 정보

NHN KCP가 가맹점의 Webhook URL로 전달하는 통보 데이터입니다.

Webhook 데이터 예시

site_cd=T0000
tno=20260715435727
order_no=TEST1234567890
tx_cd=TX00
tx_tm=20260715120500
ipgm_mnyx=1004
ipgm_name=홍길동
ipgm_time=20260715120500
totl_mnyx=1004
bank_code=20
account=T2609260001713
noti_id=26071520165018047733
op_cd=50
remitter=홍길동
cash_a_no=591605898
cash_no=26715004712417

공통 요청 파라미터

site_cdstring5

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.ex) site_cd: T0000

tnostring14

NHN KCP 거래번호입니다. 승인, 조회, 취소 등 후속 처리 시 사용하므로 반드시 저장합니다.
Webhook 통보에서는 임의로 파싱하지 말고 전체 값을 사용합니다.ex) tno: 20260715435727

order_nostring50

가맹점에서 생성한 주문번호입니다.ex) order_no: TEST1234567890

tx_cdstring4

Webhook 업무처리 구분코드입니다. 통보 유형 표의 TX00~TX07 값을 확인합니다.ex) tx_cd: TX00

tx_tmstring14

통보된 업무의 처리 완료 시각입니다. yyyyMMddHHmmss 형식으로 전달됩니다.ex) tx_tm: 20260715120500

가상계좌 입금 통보 파라미터

tx_cd: TX00인 경우 전달됩니다.

ipgm_namestring40

가상계좌 거래 건의 주문자명입니다.ex) ipgm_name: 홍길동

ipgm_mnyxnumber12

입금자가 실제 입금한 금액입니다.ex) ipgm_mnyx: 1004

totl_mnyxnumber12

해당 가상계좌에 입금된 금액의 합계입니다.ex) totl_mnyx: 1004

ipgm_timestring14

가상계좌 입금 시각입니다.ex) ipgm_time: 20260715120500

bank_codestring2

가상계좌 은행코드입니다. 발급 요청의 BK 코드가 아닌 숫자 두 자리 코드로 전달됩니다.ex) bank_code: 20

accountstring20

입금된 가상계좌번호입니다.ex) account: T2609260001713

noti_idstring20

각 입금 통보 건의 고유 값입니다. 입금과 기관 망 취소 통보에 동일한 noti_id가 전달됩니다.ex) noti_id: 26071520165018047733

op_cdstring2

가상계좌 입금 처리 결과 구분코드입니다.
50: 입금 완료, 01: 입금 재전송, 13: 입금 취소입니다. 13을 제외한 값은 입금으로 처리합니다.ex) op_cd: 50

remitterstring14

실제 입금자명입니다. 주문자명과 다를 수 있습니다.ex) remitter: 홍길동

cash_a_nostring9

현금영수증 승인번호입니다. 현금영수증 등록 요청 건에서 전달됩니다.ex) cash_a_no: 591605898

cash_nostring14

현금영수증 거래번호입니다. 현금영수증 등록 요청 건의 입금 완료 후 전달됩니다.ex) cash_no: 26715004712417

에스크로 가상계좌 환불 통보 파라미터

tx_cd: TX01인 경우 공통 파라미터와 함께 전달됩니다.

refund_nmstring20

환불받을 계좌의 예금주명입니다.

refund_mnynumber12

환불 금액입니다.

bank_codestring2

환불받을 계좌의 은행코드입니다. 은행코드표에서 BK를 제외한 숫자 코드를 사용합니다.

에스크로 구매확인·구매취소 통보 파라미터

tx_cd: TX02인 경우 공통 파라미터와 함께 전달됩니다.

st_cdstring1

구매확인 상태 코드입니다. Y: 구매확인, N: 구매취소, S: 시스템 구매확인입니다.

can_msgstring100

구매취소 사유입니다. 구매취소 통보일 경우에만 포함됩니다.

에스크로 배송시작 통보 파라미터

tx_cd: TX03인 경우 공통 파라미터와 함께 전달됩니다.

waybill_nostring50

운송장 번호입니다.

waybill_corpstring50

택배 업체명입니다.

응답 정보

가맹점은 Webhook 데이터를 DB에 정상 처리한 후 result 값을 반환해야 합니다. result 값이 없거나 0000이 아닌 경우 NHN KCP는 전송 실패로 처리하고 재전송을 시도합니다.

Response Body 예시

result=0000

응답 파라미터

result필수string4

가맹점에서 Webhook 데이터를 정상 처리한 후 NHN KCP에 반환하는 응답값입니다. 정상 처리 시 0000을 반환합니다.ex) result: 0000

가상계좌 Webhook 은행코드

가상계좌 입금·환불 통보의 bank_code는 숫자 두 자리로 전달됩니다. 가상계좌 발급 요청에 사용하는 BK 코드와 구분하여 사용하세요.

은행명	은행코드	은행명	은행코드
기업은행	03	iM뱅크	31
국민은행	04	부산은행	32
수협	07	광주은행	34
농협	11	경남은행	39
우리은행	20	우체국	71
SC제일은행	23	KEB하나은행	81
신한은행	26