인증결제 위변조 보안 가이드

인증완료시 Signature필드 값을 통해 응답 위변조 체크

  • 결제 인증처리 완료시 나이스페이는 가맹점으로 Signature 값을 전달 합니다.
  • 가맹점은 인증응답값을 조합하여 위변조대조값을 생성할 수 있고 Signature값과 비교하여 위변조 여부를 검증할 수 있습니다.
  • *위변조대조값 알고리즘 : hex(sha256(AuthToken + MID + Amt + MerchantKey))

승인완료시 Signature필드 값을 통해 응답 위변조 체크

  • 결제 승인처리 완료시 나이스페이는 가맹점으로 Signature 값을 전달 합니다.
  • 가맹점은 승인응답값을 조합하여 위변조대조값을 생성할 수 있고 Signature값과 비교하여 위변조 여부를 검증할 수 있습니다.
  • *위변조대조값 알고리즘 : Hex(sha256(TID + MID + Amt + MerchantKey))

망취소 취소 프로세스

API 호출 실패한 경우 인증 완료 후 승인 요청시 Connection time-out 발생한 경우

  • 승인 API 호출시 Connection time-out이 발생한 경우 거래대사 불일치 방지를 위해 인증응답 값을 참고하여 망취소 요청을 진행 합니다.

API 응답 실패한 경우 API 호출 후 Read time-out 발생한 경우

  • 거래대사 불일치 방지를 위해 인증응답 값을 참고하여 망취소 요청을 진행 합니다.

망취소 요청 파라미터

API https://webapi.nicepay.co.kr/webapi/cancel_process.jsp

Method POST

Content-Type application/x-www-form-urlencoded

Encoding euc-kr

파라미터명 파라미터설명
TID 30 byte 필수 거래 ID
AuthToken 40 byte 필수 인증 TOKEN
MID 10 byte 필수 상점 ID
Amt 12 byte 금액
EdiDate 14 byte 필수 요청 시간 (YYYYMMDDHHMMSS)
NetCancel 1 byte 필수 1 고정 (망취소 여부)
SignData 256 byte 필수 hex(sha256(AuthToken + MID + Amt + EdiDate + MerchantKey))
CharSet 10 byte 인증 응답 인코딩 (euc-kr / utf-8)
EdiType 10 byte 응답전문 유형 (JSON / KV) *KV:Key=value
MallReserved 500 byte 가맹점 여분 필드

망취소 응답 파라미터

  • PG사의 기능 추가에 따라 통보되는 전문의 필드가 추가될 수 있습니다. 이에 따라 가맹점에서는 인증 응답 시 필드가 추가될 수 있음을 고려해야 합니다.
파라미터명 파라미터설명
ResultCode 4 byte 필수 결제결과코드 예) 2001 *상세 내용 결과코드 참조
ResultMsg 100 byte 필수 결제결과메시지 예) 취소 성공 *상세 내용 결과코드 참조
CancelAmt 12 byte 필수 취소 금액 예) 1000원인 경우 -> 000000001000
MID 10 byte 필수 상점 ID 예) nictest00m
Moid 64 byte 필수 상점 주문번호
Signature 500 byte hex(sha256(TID + MID + CancelAmt + MerchantKey)), 위변조 검증 데이터
응답 데이터 유효성 검증을 위해 가맹점 수준에서 비교하는 로직 구현을 권고합니다.
PayMethod 10 byte
CARD : 신용카드
BANK : 계좌이체
VBANK : 가상계좌
CELLPHONE : 휴대폰결제
TID 30 byte 거래 ID
CancelDate 8 byte 취소일자 (YYYYMMDD)
CancelTime 6 byte 취소시간 (HHmmss)
CancelNum 8 byte 취소번호
RemainAmt 12 byte 취소 후 잔액 예) 잔액이 1000원인 경우 -> 000000001000
MallReserved 500 byte 가맹점 여분 필드

모바일 결제 인증 요청/응답 실패 처리 가이드

v3Payment.jsp submit 후 결제창 노출에 실패하는 경우 인증 요청이 실패한 경우

인증 응답에 실패 하는 경우 결제창은 노출 되었으나 인증 응답이 없는 경우

  • ReturnURL 파라미터에 설정한 URL값을 확인 합니다. URL은 절대경로로 설정하고, 443포트가 접근 가능하도록 설정 합니다.
  • 모바일 인증 응답은 ReturnURL 파라미터에 설정한 URL값으로 리턴 합니다.
  • SSL인증서 정상 적용 여부를 체크 합니다. 인증서 만료 혹은 SSL 사용이 불가한 경우 인증 응답 처리가 원활 하지 않을 수 있습니다.

PC 결제 인증 요청/응답 실패 처리 가이드

goPay()함수 호출에 실패하는 경우 PC 결제창 호출에 실패한 경우

  • https://web.nicepay.co.kr/v3/webstd/js/nicepay-3.0.js 정상 import 여부를 체크 합니다.
  • nicepay-3.0.js는 반드시 import 하여 사용하고 해당 js를 별도로 다운로드 및 변조 하지 않도록 주의 합니다.
  • goPay() 함수는 Document form object를 매개변수로 사용 합니다. 결제창 호출시 goPay() 함수로 원하는 form object가 전달 되었는지 디버깅 합니다.
  • 브라우저의 자바스크립트 허용처리가 되었는지, 최신 웹표준 지원 브라우저를 사용하고 있는지 체크 합니다.

사용자가 결제 인증에 실패 하는경우 결제창은 노출 되었으나 인증 응답이 없는 경우

  • 인증 성공/실패시 nicepaySubmit()함수를 call-back 하고 인증 성공/실패 object는 goPay()함수로 전달된 form object에 append 됩니다.
  • 샘플코드는 nicepaySubmit(){ document.payForm.submit(); } 처럼 client-side에서 target server-side로 submit 하도록 처리 되어 있습니다.
  • 인증 응답을 별도 핸들링 원하는 경우 nicepaySubmit() call-back event를 활용 합니다.
  • 일반적으로 nicepaySubmit()함수 call-back event를 통해 예외 핸들링이 가능 합니다.
  • 하지만 사용자가 브라우저를 강제 종료하는 경우 nicepaySubmit()함수 call-back event를 확인 할수 없기 때문에 인증응답 예외 처리는 negative한 관점으로 운영할 필요가 있습니다.

사용자가 결제창 종료 버튼을 클릭 하는경우 결제창 종료 이벤트 처리

  • 사용자가 결제창 종료 버튼을 클릭하는 경우 nicepayClose()함수를 call-back 합니다.
  • 가맹점은 해당 event를 활용하여 페이지 이동 혹은 알림 메시지를 client에게 전달 할 수 있습니다.