본문으로 건너뛰기

결제창 호출하기

PC·Mobile 환경에서 나이스페이 결제창을 호출하고 인증 응답을 수신하는 방법을 설명합니다.

1. 결제창 호출 Flow​

PC 결제창 호출​

  1. goPay() 함수로 결제창 레이어 팝업을 호출합니다.
  2. 결제창 dim 처리는 goPay() 호출 시 전달한 form element 기준으로 처리됩니다.
  3. 사용자 인증 완료 시 결제창이 nicepaySubmit()을 콜백합니다.
  4. 콜백과 동시에 인증 결과 form이 form action target으로 submit 됩니다.
  5. 가맹점 server-side에서 인증 결과를 수신한 뒤 승인 API 연동을 진행합니다.

MOBILE 결제창 호출​

  1. goPay() 호출 후 결제 파라미터를 가공해 결제창으로 submit 합니다.
  2. 사용자가 결제창에서 인증사를 선택하고 인증을 진행합니다.
  3. 중요: 인증 완료 후 인증 응답은 최초 결제창 호출 시 ReturnURL에 설정한 URL로 리턴됩니다.
  4. 가맹점 server-side에서 인증 결과를 수신한 뒤 승인 API 연동을 진행합니다.
  5. WebView로 모바일 결제를 구현하는 경우 WapUrl, IspCancelUrl을 반드시 추가합니다. (APP WebView 연동 문서 참고)

2. 설명 (Description)​

  • PC와 Mobile 결제창 호출 방식의 차이를 이해한 뒤 인증 응답 수신 흐름을 구현합니다.
  • 결제창 JS SDK: https://pg-web.nicepay.co.kr/v3/common/js/nicepay-pgweb.js (필수 import)
  • goPay(document.yourFormObject) — form object 전달, 인코딩 EUC-KR
  • 인증 응답 AuthResultCode가 0000인 경우 승인 API 연동을 진행합니다. 인증 성공 ≠ 승인 성공입니다.
  • 민감 정보(MerchantKey, SignData 생성 등)는 반드시 server-side에서 처리하고 외부에 노출하지 않습니다.
  • 샘플 소스는 프로세스 설명용이며, 운영 환경에 그대로 사용하여 발생하는 문제에 대해서는 나이스정보통신의 책임이 없는 점 주의하시기 바랍니다.

3. 결제창 호출 (Request)​

3.1. 호출 방식​

항목값
JavaScripthttps://pg-web.nicepay.co.kr/v3/common/js/nicepay-pgweb.js
FunctiongoPay(document.yourFormObject)
TypeHTML Form object
Encodingeuc-kr

3.2. 요청 파라미터​

필드명크기(byte)필수설명
GoodsName40O결제상품명 (euc-kr). 쌍따옴표 ", 대괄호 [] 등 특수기호 사용 시 별도 문의
Amt12O금액 (숫자만)
MID10O가맹점 아이디
EdiDate14O요청 시간 (YYYYMMDDHHMISS)
Moid64O상품주문번호. 숫자·영문 조합의 고유값 권장
SignData500O위변조 검증 데이터, 생성규칙: hex(sha256(EdiDate + MID + Amt + MerchantKey))
PayMethod10O결제수단 (CARD: 신용카드, BANK: 계좌이체, VBANK: 가상계좌, CELLPHONE: 휴대폰 소액결제)
ReturnURL500Mobile 필수인증 응답 URL (절대 경로)
BuyerName30구매자명 (euc-kr)
BuyerTel20구매자 연락처 (숫자만)
ReqReserved500가맹점 여분 필드
BuyerEmail60구매자 이메일
CharSet12인증 응답 인코딩 (euc-kr 기본 / utf-8)
VbankExpDate12가상계좌 결제 시 계좌의 입금만료일 설정, 8자리 (YYYYMMDD) 또는 12자리 (YYYYMMDDHHMi) 설정 가능
GoodsCl1휴대폰 소액결제 시 필수, 상품 구분 (0: 컨텐츠, 1: 실물)
ConnWithIframe1iframe 연동 시 Y (iframe 기반 호출 시만)
WapUrl500APP WebView: 가맹점 App Scheme, 제휴사 앱 인증 후 가맹점 앱 복귀 시 사용
IspCancelUrl500APP WebView: ISP 취소 시 앱 복귀 스킴 url

기능별 옵션 파라미터​

아래 내용은 가맹점 MID 설정에 따라 추가로 사용 가능한 파라미터들을 항목별로 정리하였습니다. 영업담당자와 사전 협의 후 사용하시기 바랍니다. (사전협의 없이 사용하는 경우 결제 혹은 취소 시 실패가 발생할 수 있습니다.)

  • 과세 및 면세 지정 옵션 (사용 시 4개 필드의 합이 Amt 값과 일치해야 합니다.)
필드명크기(byte)설명
SupplyAmt12공급가액
GoodsVat12부가세
ServiceAmt12봉사료
TaxFreeAmt12면세 금액
  • 가맹점 분담 무이자 설정 옵션
필드명크기(byte)설명
ShopInterest1가맹점 분담 무이자 사용 여부 (0: 미사용, 1: 사용)
QuotaInterest-ShopInterest=1 설정 시 사용 가능, 기준정보에 등록된 무이자 할부 정보 중 사용할 할부 옵션 설정
QuotaInterest 옵션 설정 방법
  • 공백 설정 시 오류 발생
  • | 를 구분자로 하여 카드 코드 나열
  • : 를 구분자로 하여 카드 코드와 할부개월 구분
  • , 를 구분자로 하여 할부개월 나열
  • 형식: 카드코드:할부개월,할부개월|카드코드:할부개월,할부개월|...
  • 예시: 01:06,07|02:06:07
    • 가맹점 분담 무이자 옵션 사용 시 비씨카드 6,7 개월과 국민카드 6,7개월 설정

4. 결제창 응답 (Response)​

4.1. 응답 파라미터​

인증 응답 파라미터는 PC/Mobile 동일합니다.

PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.

필드명크기(byte)설명
AuthResultCode4인증 결과 코드 (0000: 성공, 그 외 실패)
AuthResultMsg2000인증 결과 메시지
AuthToken40인증 토큰
PayMethod10결제수단 (CARD / BANK / VBANK / CELLPHONE)
MID10가맹점 아이디
Moid64상품 주문번호
Signature500hex(sha256(AuthToken + MID + Amt + MerchantKey)) — 위변조 검증 권장
Amt12금액
ReqReserved500가맹점 여분 필드
TxTid30거래 ID
NextAppURL255인증 성공 시 승인 요청 URL (POST)
NetCancelURL255인증 성공 시 망취소 요청 URL

NextAppURL 예시 (둘 중 하나 응답)

  • https://dc1-api.nicepay.co.kr/webapi/pay_process.jsp
  • https://dc2-api.nicepay.co.kr/webapi/pay_process.jsp

NetCancelURL 예시 (둘 중 하나 응답)

  • https://dc1-api.nicepay.co.kr/webapi/cancel_process.jsp
  • https://dc2-api.nicepay.co.kr/webapi/cancel_process.jsp

4.2 PC 인증 응답 처리 관련 참고 사항​

  • goPay() 호출 시 전달한 form에 인증 응답 필드가 append 됩니다.
  • nicepaySubmit() 콜백 후 form이 가맹점 server-side로 submit 됩니다.
  • AJAX 방식으로 후속 승인 API를 연동하는 경우 nicepaySubmit() 시점에 form에서 인증 응답 값을 추출해 가맹점 server-side로 전달해야 합니다 (Cross Domain 미지원).

5. 예시​

아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다. 가맹점 Key, ReturnURL 등은 가맹점 환경에 맞게 사용하셔야 합니다.

5.1. 요청 예시​

<head>
<script src="https://pg-web.nicepay.co.kr/v3/common/js/nicepay-pgweb.js"></script>
<script type="text/javascript">
//[PC 결제창 전용]결제 최종 요청시 실행됩니다. <<'nicepaySubmit()' 이름 수정 불가능>>
function nicepayStart(){
	goPay(document.payForm);
}


//[PC 결제창 전용]결제 최종 요청시 실행됩니다. <<'nicepaySubmit()' 이름 수정 불가능>>
function nicepaySubmit(){
	document.payForm.submit();
}

//[PC 결제창 전용]결제창 종료 함수 <<'nicepayClose()' 이름 수정 불가능>>
function nicepayClose(){
	alert("결제가 취소 되었습니다");
}

</script>
</head>
<body>
<form name="payForm" method="post">
  <input type="hidden" name="GoodsName" value="나이스페이" />
  <input type="hidden" name="Amt" value="1004" />
  <input type="hidden" name="MID" value="nictest00m" />
  <input type="hidden" name="EdiDate" value="20260813090616" />
  <input type="hidden" name="Moid" value="testRequest1" />
  <input type="hidden" name="SignData" value="f96273567e5fe257d10bf5d8b637aa96da68f1229314756da2324bab022bc3e8" />
  <input type="hidden" name="PayMethod" value="CARD" />
  <input type="hidden" name="ReturnURL" value="https://merchant.example.com/pay/return" />
</form>
<a href="#" onClick="nicepayStart();">결제하기</a>
</body>

SignData = hex(sha256(EdiDate + MID + Amt + MerchantKey))

5.2. 응답 예시​

POST /pay/return HTTP/1.1
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded

AuthResultCode=0000&AuthResultMsg=인증 성공&AuthToken=NICETOKN5AC64335B5407F799C440DEECE7A3ED5&PayMethod=CARD&MID=nictest00m&Moid=testRequest1&Signature=f49a70d606ef46d95d4f69e796b06ded9ea94d5a28e08383cbea12abe9199dad&Amt=1004&TxTid=nictest00m01012608131607041648&NextAppURL=https://dc1-api.nicepay.co.kr/webapi/pay_process.jsp&NetCancelURL=https://dc1-api.nicepay.co.kr/webapi/cancel_process.jsp

6. 연동 시 주의사항​

  • 결제창 호출 시 인코딩은 euc-kr 으로만 설정합니다.
  • 인증 응답 수신 후 금액(Amt) 위변조 여부를 가맹점에서 검증해야 합니다.
  • 구간별 로그 보관 시 가맹점 서비스 운영 및 장애 대응에 유연하게 처리 가능합니다.
  • 샘플 코드 및 연동 문의는 it@nicevan.co.kr 메일로 전달 부탁드립니다.

7. 관련 문서​