본문으로 건너뛰기

회원등록/결제요청 화면 호출하기

1. 회원등록/결제요청 Flow​

2. 설명 (Description)​

  • 고객 결제 요청 시 나이스페이의 화면을 통해 등록된 결제수단(카드 또는 계좌) 중 하나를 선택 후 결제 비밀번호를 검증하는 서비스입니다.
  • 신규 회원 가입 시 본인인증 및 결제 비밀번호 등록 화면이 노출됩니다.

3. 요청 (Request)​

3.1. HTTP Request​

  • Method: POST
  • URL: https://payu.nicepay.co.kr/main.do
  • Content-Type: application/x-www-form-urlencoded
  • Encoding: EUC-KR
PC/Mobile 화면 호출 관련 참고 사항
  • PC 환경: POPUP(420*670) 생성 후 form data submit
  • 모바일 환경: form data submit

3.2. 요청 파라미터​

필드명크기(byte)필수설명
MID10O가맹점 아이디
MallUserID20O거래 아이디
UserKey70회원 등록 시 발급된 고객 Key (신규 회원 가입 시 빈 값으로 요청)
AuthType1신규 회원 가입 시 고객 검증 타입 (1: CI 검증, 2: 고객명, 전화번호 검증)
BuyerIdentity-AuthType을 1로 세팅한 경우 필수 고객 검증 키, 생성 규칙: hex(sha256(고객CI))
BuyerName30O고객명
BuyerTel20O고객 전화번호 (숫자만 입력)
BuyerEmail60O고객 Email
Moid64O가맹점 주문번호 (고유한 값으로 설정, 나이스페이 가공 없음)
EdiDate14O요청 전문 생성 일시(YYYYMMDDHHMISS)
Amt12O결제 요청 금액
GoodsName40O상품명 (특수기호 사용 시 별도 문의)
ReturnUrl200O결제 화면 호출 후 결과를 수신받을 가맹점 측 URL
SignData256O위변조 검증 데이터, 생성규칙: hex(sha256(EdiDate + MID + Amt + MerchantKey))
RcvName10O수취인 이름
RcvTel10O수취인 전화번호
RcvPostNo10O배송지 우편번호
RcvAddr110O배송지 주소
RcvAddr210O배송지 상세 주소
CharSet10인증 응답 인코딩 (euc-kr(default) / utf-8)

기능별 옵션 파라미터​

아래 내용은 가맹점 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. 응답 파라미터​

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

필드명크기(byte)설명
AuthResultCode4결과코드 (0000: 성공, 이외 실패)
AuthResultMsg100결과 메세지
AuthToken40인증 토큰, 마이페이지 호출에 대한 고유 key 값
PayMethod10고객이 선택한 결제 수단 코드 (CARD: 신용카드, CMS_BANK: 계좌간편결제)
MID10가맹점 ID
Moid64가맹점 주문번호
Amt12결제 요청 금액
TrKey30승인 요청 key
TxTid30승인 거래 매핑을 위한 거래 ID
MallUserID20가맹점에서 요청한 고객 ID
UserKey100간편결제 고객 Key (신규 회원 가입 시 해당 값 반드시 저장)
ApprovalMID10인증/승인 분리 처리 요청한 MID
EdiDate14인증결과 응답 생성 일시 (YYYYMMDDHHMISS)
NextAppURL255최종 결제를 위해 승인 요청할 URL
NetCancelURL255거래 불일치 방지를 위한 망취소 요청 URL

5. 예시​

아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.

5.1. 요청 예시​


<form method="post" action="https://payu.nicepay.co.kr/main.do">
  <!-- 필수 파라미터 -->
  <input type="hidden" name="MID" value="payutest0m" />
  <input type="hidden" name="MallUserID" value="payuTEST" />
  <input type="hidden" name="UserKey" value="" />
  <input type="hidden" name="BuyerName" value="나이스" />
  <input type="hidden" name="BuyerTel" value="01012345678" />
  <input type="hidden" name="BuyerEmail" value="test@abc.com" />
  <input type="hidden" name="Moid" value="TEST_123" />
  <input type="hidden" name="EdiDate" value="20260814111541" />
  <input type="hidden" name="Amt" value="1004" />
  <input type="hidden" name="GoodsName" value="테스트상품" />
  <input type="hidden" name="ReturnUrl" value="http://localhost:8080/payu" />
  <input type="hidden" name="RcvName" value="나이스" />
  <input type="hidden" name="RcvTel" value="01000000000" />
  <input type="hidden" name="RcvPostNo" value="00000" />
  <input type="hidden" name="Amt" value="1004" />
  <input type="hidden" name="RcvAddr1" value="서울특별시 테스트구 샘플로" />
  <input type="hidden" name="RcvAddr2" value="테스트빌딩 101호" />
  <input type="hidden" name="SignData" value="6f550db59c7f2091adc1565e80ea1933121c060e749e178444ce830daff9cb9f" />
  
  <!-- 추가 파라미터 -->
  <input type="hidden" name="CharSet" value="" />

  <!-- 요청 버튼 -->
  <button type="submit">요청하기</button>
</form>

5.2. 응답 예시​

{
  "EdiDate": "20260814111619",
  "NetCancelURL": "https://webapi.nicepay.co.kr/webapi/cancel_process.jsp",
  "UserKey": "PAYTKN816bdce64a149f2af7e90603a57446716af2b0a9f34e1427352c5405f2a6acf0",
  "NextAppURL": "https://webapi.nicepay.co.kr/webapi/pay_process.jsp",
  "CharSet": "euc-kr",
  "MID": "payutest0m",
  "Amt": "1004",
  "ReturnUrl": "http://localhost:8080/payu",
  "MallUserID": "payuTEST",
  "TrKey": "TRKYpayutest0m2608141116193241",
  "AuthResultMsg": "정상 처리되었습니다.",
  "PayMethod": "CARD",
  "AuthToken": "PAYTOKEN269E752BA68B1F3508DC34FA332A1C26",
  "Moid": "TEST_123",
  "ApproveMode": "API",
  "TxTid": "payutest0m01012608141116191323",
  "AuthResultCode": "0000"
}