hook.md

웹훅

웹훅 | 더 알아보기

Over-view

설명

나이스페이 API의 결제수단의 이벤트 발생시 등록된 🔔 웹훅 End-point로 이벤트 결과를 전달하는 기능입니다.
가상계좌 처럼 계좌 생성과 입금의 차이가 발생하는 결제 수단은 반드시 웹훅 개발이 필요 합니다.

웹훅 발송 흐름

• 등록된 웹훅 End-point로 이벤트 발생시 웹훅 전문 Post
• 가맹점은 Server에서 웹훅 전문 확인 후 비즈니스 로직을 처리
• 비즈니스 로직 처리 후 HTTPStatus 200과 ResponseBody에 "OK” 문자열을 print하여 응답
  • 응답 시에는 Content-Type: text/html 타입으로 응답하여야 합니다.

웹훅 발송 시점

• 💳 결제(승인) 되었을 때(모든 지불수단)
• 가상계좌가 발급(채번) 되었을 때
• 가상계좌에 결제금액이 입금 되었을 때
• 결제가 취소 처리되었을 때 (API 또는 가맹점관리자 취소)

웹훅 기능 요약

• 추가 : 결제수단을 선택하여 웹훅을 추가 하는 기능
• TEST 호출 : 웹훅 등록 후 등록된 End-point로 Test 전문을 전달하는 기능
• 재전송 : 웹훅 전송 실패 처리 가이드
• 로그 : 전달된 웹훅의 로그 확인 가이드

⚠️ 중요

Response body에 "OK” 문자열이 없는 경우 실패로 처리되기 때문에 주의가 필요 합니다. 나이스페이먼츠에서 보내는 Content-Type은 application/json 타입이나, 가맹점에서 응답 시에는 Content-Type: text/html 타입으로 응답해주셔야 합니다. 방화벽 정책을 통해 Inbound IP 를 제한하는 것을 권장하고 있습니다.
비즈니스 로직 처리 전 웹훅 전문에 포함된 위변조 검증값 signature 과 금액을 반드시 체크 해주세요.

결제통보 요청 명세 (Nicepayment -> merchant)

Content-type: application/json;charset=utf-8

Parameter	Type	필수	Byte	설명
resultCode	String	O	4	결제결과코드 0000 : 성공 / 그외 실패
resultMsg	String	O	100	결제결과메시지
tid	String	O	30	결제 승인 키 최초 승인(가상계좌-채번)에 성공한 원거래의 NICEPAY 거래키 입니다.
cancelledTid	String		30	취소 거래 키 NICEPAY가 발행하는 취소 응답 TID (부분취소시 tid와 다른 값이 응답됨) - 취소 요청건에 한하여 응답됨 - cancels 객체에서 현재 취소된 거래정보를 찾을 때 사용 하시면 됩니다.
orderId	String	O	64	상점 거래 고유번호
ediDate	String	O	-	응답전문생성일시 ISO 8601 형식
signature	String		256	위변조 검증 데이터 - 유효한 거래건에 한하여 응답 - 생성규칙 : hex(sha256(tid + amount + ediDate+ SecretKey)) - 데이터 유효성 검증을 위해, 가맹점 수준에서 비교하는 로직 구현 권고 - SecretKey는 가맹점관리자에 로그인 하여 확인 가능합니다.
status	String	O	20	결제 처리상태 paid:결제완료, ready:준비됨, failed:결제실패, cancelled:취소됨, partialCancelled:부분 취소됨, expired:만료됨 ['paid', 'ready', 'failed', 'cancelled', 'partialCancelled', 'expired']
paidAt	String	O	-	결제완료시점 ISO 8601 형식 결제완료가 아닐 경우 0
failedAt	String	O	-	결제실패시점 ISO 8601 형식 결제실패가 아닐 경우 0
cancelledAt	String	O	-	결제취소시점 ISO 8601 형식 결제취소가 아닐 경우 0 부분취소인경우, 가장 마지막건의 취소 시간
payMethod	String	O	10	결제수단 card:신용카드, vbank:가상계좌, bank:계좌이체, cellphone:휴대폰, naverpay=네이버페이, kakaopay=카카오페이, samsungpay=삼성페이
amount	Integer	O	12	결제 금액
balanceAmt	Integer	O	12	취소 가능 잔액 부분취소 거래인경우, 전체금액에서 현재까지 취소된 금액을 차감한 금액.
goodsName	String	O	40	상품명
mallReserved	String		500	상점 정보 전달용 예비필드 returnUrl로 redirect되는 시점에 반환 됩니다. JSON string format으로 이용하시기를 권고 드립니다. 단, 큰따옴표(")는 이용불가
useEscrow	Boolean	O	-	에스크로 거래 여부 false:일반거래 / true:에스크로 거래
currency	String	O	3	결제승인화폐단위 KRW:원화, USD:미화달러, CNY:위안화
channel	String		10	pc:PC결제, mobile:모바일결제 ['pc', 'mobile', 'null']
approveNo	String		30	제휴사 승인 번호 신용카드, 계좌이체, 휴대폰
buyerName	String		30	구매자 명
buyerTel	String		40	구매자 전화번호
buyerEmail	String		60	구매자 이메일
issuedCashReceipt	Boolean		-	현금영수증 발급여부 true:발행 / false:미발행
receiptUrl	String		200	매출전표 확인 URL
mallUserId	String		20	상점에서 관리하는 사용자 아이디

할인 정보

Parameter		Type	필수	Byte	설명
coupon		Object		-	즉시할인 프로모션 정보
	couponAmt	Integer		12	즉시할인 적용된 금액

카드

Parameter		Type	필수	Byte	설명
card		Object			신용카드 정보
	cardCode	String	O	3	신용카드사별 코드
	cardName	String	O	20	결제 카드사 이름 예) 비씨
	cardNum	String		20	카드번호 앞 6자 마지막 4자를 제외한 가운데 숫자 마스킹 처리됨 예) 536112******1234 - 카카오머니/네이버포인트/페이코포인트 전액결제 거래인경우 null
	cardQuota	String	O	3	할부개월 0:일시불, 2:2개월, 3:3개월 …
	isInterestFree	Boolean	O	-	상점분담무이자 여부 true:무이자, false:일반
	cardType	String		1	카드 구분 credit:신용, check:체크
	canPartCancel	String	O	-	부분취소 가능 여부 true:가능, false:불가능
	acquCardCode	String	O	3	매입카드사코드
	acquCardName	String	O	100	매입카드사명

현금영수증

Parameter		Type	필수	Byte	설명
cashReceipts		Array			현금영수증 발급정보 -NaverPay-포인트 ,가상계좌 입금건에서 제공 -부분 취소시, 2건이상 존재가능
	receiptTid	String	O	30	현금영수증 TID
	orgTid	String	O	30	연관된 원 승인/취소 거래 TID 부분취소시, 원 부분취소 거래건의 TID와 매핑됨 - 원거래를 부분취소 하면, 신규 TID가 채번되고, 채번된 부분취소 TID가 셋팅 됩니다.
	status	String	O	20	발급진행 상태 [발급] issueRequested : 발급 접수 완료[1,3] issueReqCancelled : 요청회수(국세청 발행 접수전 거래의 발급취소(배치 형태의 거래에서 발생[2]) issued : 국세청 발급 완료[4] issueFailed : 발급실패(제휴사(더빌) 실패[9] 또는 국세청 실패[10]) [취소] cancelRequested : 취소 접수 완료[1,3] cancelReqCancelled : 요청회수(국세청 취소 접수전 거래의 발급취소(배치 형태의 거래에서 발생[2]) cancelled : 국세청 취소 완료[4] cancelFailed : 발급실패(제휴사(더빌) 실패[9] 또는 국세청 실패[10])
	amount	Integer	O	12	현금영수증 발행 총금액
	taxFreeAmt	Integer	O	12	현금영수증 전체 금액중에서 면세금액
	receiptType	String	O	20	현금영수증 타입 individual : 개인 소득공제용 company : 사업자 지출증빙용
	issueNo	String	O	30	현금영수증 국세청 발행번호
	receiptUrl	String	O	200	현금영수증 매출전표 확인 URL

계좌이체

Parameter		Type	필수	Byte	설명
bank		Object			은행 정보
	bankCode	String	O	3	결제은행코드 (은행코드 참조)
	bankName	String	O	20	결제은행명 (euc-kr)

가상계좌

Parameter		Type	필수	Byte	설명
vbank		Object			가상계좌 정보
	vbankCode	String	O	3	가상계좌 은행코드
	vbankName	String	O	20	가상계좌 은행명
	vbankNumber	String	O	20	가상계좌 번호
	vbankExpDate	String	O	-	가상계좌 입금 만료일 ISO 8601
	vbankHolder	String	O	40	가상계좌 예금주명

취소

Parameter		Type	필수	Byte	설명
cancels		Array			취소/부분취소 내역
	tid	String	O	30	승인 취소 거래번호
	amount	Integer	O	12	취소금액
	cancelledAt	String	O	-	취소된 시각 ISO 8601
	reason	String	O	100	취소사유
	receiptUrl	String	O	200	취소에 대한 매출전표 확인 URL
	couponAmt	Integer		12	쿠폰 취소금액

결제통보 응답 명세 (merchant -> Nicepayment)

Content-type: text/html;charset=utf-8

value		Type	필수	Byte	설명
"OK"		String	O	-	정상응답 하였다는 의미로 "OK" 문자열을 검증합니다.

더 알아보기

결제 개발을 위해 더 상세한 정보가 필요하다면📌 공통 탭의 정보를 활용하고,
API 개발을 위한 각 인터페이스의 개발 명세가 필요하다면 📚 문서 탭의 자료를 확인 해주세요.
개발이 완료되어 운영에 필요한 정보와 Tip은 ☸️ 운영 탭의 정보를 통해 확인이 가능 합니다.

📌 공통

개발 전 필요한 공통적인 가이드 입니다.

• 개발 준비 👉 회원가입 | API KEY확인 | 방화벽 정책 | IP 보안기능 | 타임아웃 정보
• API·JS SDK 👉 URI 목록 | JS SDK목록 | API KEY | API·JS SDK인증 | Basic auth | Bearer token
• TEST·샘플코드 👉 샌드박스 TEST | 샌드박스 활용 | 웹로그 디버깅 | 샘플코드
• 코드집 👉 HTTP-상태코드 | 카드코드 | 은행코드 | JS SDK 응답코드 | API 응답코드

📚 문서

API 명세와 코드가 포함된 기술문서 입니다.

• 결제·발급 👉 결제창 | 빌링 | 현금영수증 | Access token
• 조회 👉 거래 조회 | 약관 조회 | 카드 이벤트 조회 | 카드 무이자 조회
• 취소·환불·망취소 👉 취소·환불 | 망 취소
• 웹훅 👉 웹훅
• APP 👉 iOS | iOS Swift | iOS Objective-c | Android | Android java | Android kotlin

☸️ 운영

운영에 필요한 정보 입니다.

• 지원환경 👉 개발환경 | 지원 브라우저
• 오류관리 👉 오류관리
• 개발정보 👉 기능 요약 | KEY 정보 | ip보안(ip접근제한) | 웹훅 | 로그