결제통보 연동하기
본 문서는 결제(승인) 완료 후 나이스정보통신에서 가맹점의 URL/IP로 승인 결과를 통보(웹훅)하는 서비스에 대한 규격을 정의합니다.
1. 결제통보 Flow
2. 설명 (Description)
- 결제가 완료되면 승인 결과 데이터를 가맹점이 지정한 URL 또는 IP:Port로 통보합니다.
- 가상계좌는 발급 후 입금이 완료되어야 승인 결과가 통보됩니다. 입금 전에는 별도 통보가 없습니다.
- 통보 데이터는 server-side에서만 처리하고, 민감 정보가 노출되지 않도록 합니다.
- 한글 데이터 통보 인코딩은 EUC-KR입니다.
3. 연동 전 필수 설정
가맹점관리자페이지: 메인화면 → 가맹점정보
| 항목 | 설명 |
|---|---|
| 지불수단 | 통보를 수신할 결제수단 |
| 관리자이메일 | 통보 실패 시 사유 수신 메일 |
| URL/IP | 수신 URL 또는 IP, Port |
| 재전송 간격 | 실패 후 재통보 간격 (1~10분) |
| 재전송 횟수 | 재통보 횟수 (최대 10회) |
| OK 체크 | TCP/IP 방식 시 성공 시 OK 문자열 출력 여부 (필수) |
| 미전송시 체크 | 통보 미사용 지불수단 |
방화벽 (INBOUND)
| 프로토콜 | 연결 대상 |
|---|---|
| HTTPS / TCP | 121.133.126.10, 121.133.126.11, 211.33.136.39 |
- URL 입력 시 HTTPS, IP·Port 입력 시 TCP로 통신합니다.
4. 주의사항
- 가맹점 수신 실패 시 통보 실패 처리 후 실패 사유를 메일로 전송합니다.
- PG 기능 추가에 따라 통보 필드가 추가될 수 있음을 고려하세요.
5. 통보 파라미터
5.1. 공통
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| Amt | 12 | 상품금액 |
| AuthCode | 30 | 승인번호 |
| AuthDate | 12 | 승인일시 (YYMMDDHHMISS) |
| BuyerAuthNum | 15 | 구매자 식별번호 |
| BuyerEmail | 60 | 구매자 이메일 |
| FnCd | 4 | 제휴사코드 |
| FnName | 20 | 제휴사명 |
| GoodsName | 40 | 상품명 |
| MallUserID | 20 | 고객 ID |
| MID | 10 | 가맹점 ID |
| MOID | 64 | 주문번호 |
| name | 30 | 구매자명 |
| PayMethod | 10 | 지불수단 |
| RcptAuthCode | 30 | 현금영수증 승인번호 |
| RcptTID | 30 | 현금영수증 TID |
| RcptType | 1 | 현금영수증 타입 (0/1/2) |
| ReceitType | 1 | RcptType과 동일 |
| ResultCode | 4 | 결과코드 |
| ResultMsg | 100 | 결과메시지 |
| StateCd | 1 | 거래 상태 (0:승인, 1:전취소, 2:후취소) |
| TID | 30 | 거래 ID |
| CancelDate | 12 | 취소일시 |
| CancelMOID | 64 | 취소요청 주문번호 (신용카드 취소 통보 시) |
| TransType | 1 | 에스크로 (0:일반, 1:에스크로) |
| MallReserved | 500 | 가맹점 여분필드 |
| MallReserved1~10 | 예비 필드 (2~10은 미사용 시 빈 값) |
5.2. 카드
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| CardNo | 16 | 카드번호 (마스킹) |
| CardQuota | 2 | 할부개월 |
| SUB_ID | 20 | 서브 아이디 |
| AcquCd | 3 | 매입사 코드 |
| AcquName | 20 | 매입사명 |
| ClickpayCl | 2 | 간편결제 구분 |
| TermNo | 20 | CATID |
| EdiNo | 20 | 전문관리항목 |
| CardCl | 2 | 0:신용, 1:체크 |
| CardType | 2 | 01:개인, 02:법인, 03:해외 |
5.3. 가상계좌
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| VbankInputName | 20 | 입금자명 |
| VbankName | 20 | 가상계좌 은행명 |
| VbankNum | 20 | 가상계좌 번호 |
6. 예시
테스트용 샘플 데이터이며 실제 운영 값으로 사용하지 마세요.
6.1. HTTPS 통보 수신 (개념)
가맹점 endpoint에서 POST form 파라미터로 수신 후 ResultCode, TID, Amt 등을 검증하고 주문 상태를 갱신합니다.
6.2. TCP 통보
IP·Port로 수신 시 응답 본문에 OK 를 출력해야 합니다 (관리자 설정의 OK 체크 사용 시).