본문으로 건너뛰기

가상계좌 발급하기

가상계좌 발급 API Flow​

2. 설명 (Description)​

  • 가상계좌 발급 API는 고객(구매자)에게 일회성 입금 전용 계좌번호를 발급하는 서비스입니다.
  • 입금이 완료되면 은행을 통해 나이스페이를 거쳐 가맹점으로 가상계좌 입금 건에 대하여 통보하고 가맹점은 해당 데이터를 받아 결제 완료 처리합니다.
  • 통보에 대한 내용은 결제통보 페이지를 참고하여 연동하시기 바랍니다.
  • 해당 문서에서는 가상계좌 발급 서비스에 필요한 기본적인 파라미터 위주로 기재하고 있습니다.
    이외 부가적인 기능을 원하시는 경우 영업담당자를 통해 가능 여부를 협의하시기 바랍니다.

3. 요청 (Request)​

3.1. HTTP Request​

  • Method: POST
  • URL: https://webapi.nicepay.co.kr/webapi/get_vacount.jsp
  • Content-Type: application/x-www-form-urlencoded
  • Encoding: EUC-KR

3.2. 요청 파라미터​

필드명크기(byte)필수설명
TID30O거래 아이디, TID 생성규칙 항목 참고
MID10O가맹점 아이디
EdiDate14O전문생성일시 (YYYYMMDDHHMISS)
Moid64O가맹점 주문번호, (고유한 값으로 설정, 나이스페이 가공 없음)
Amt12O결제 금액
GoodsName40O상품명
SignData256O위변조 검증 데이터, 생성 규칙: hex(sha256(MID + Amt + EdiDate + Moid + MerchantKey))
CashReceiptType1O현금영수증 발행 요청 타입 (0: 미발행, 1: 소득공제, 2: 지출증빙)
ReceiptTypeNo11현금영수증 발급번호, CashReceiptType 값을 1 또는 2로 입력한 경우 필수
BankCode3O은행코드, 가상계좌 발급 가능 은행 리스트는 은행코드 페이지 참조
VbankExpDate12O가상계좌 입금만료일, 8자리(YYYYMMDD) 또는 12자리(YYYYMMDDHHMI) 입력
VbankAccountName30가상계좌 예금주명, 해당 파라미터 사용 전 영업담당자와 협의 필요
BuyerEmail60구매자 이메일 주소
BuyerTel20구매자 전화번호
BuyerName30구매자명
CharSet10인증 응답 인코딩 (euc-kr(default) / utf-8)
EdiType10응답전문 유형 (JSON(default) / KV) *KV:Key=value
현금영수증 발급번호 입력 규칙

현금영수증 발급번호는 CashReceiptType의 값에 따라 아래와 같이 입력하여야 합니다.
( - 기호 없이 숫자만 입력합니다.)

  • 소득공제(CashReceiptType=1)인 경우, 휴대폰번호 11자리 입력
  • 지출증빙(CashReceiptType=2)인 경우, 사업자번호 10자리 입력

TID 생성규칙​

생성 규칙
  • MID(10) + 지불수단(2) + 매체구분(2) + 시간정보(12) + 랜덤(4)
  • 크기: 30 byte
  • 설명:
    • MID: 가맹점 아이디 (문자열 끝은 소문자 m으로 기재되어야 함.)
    • 지불수단: 결제수단별 코드 (03: 가상계좌)
    • 매체구분: 거래 형태 (01: 일반)
    • 시간정보: 결제 요청 일시 (YYMMDDHHMISS)
    • 랜덤: 거래를 식별하기 위한 임의의 값 4자리
  • TID 생성 예시: nictest00m01012605061948280471

4. 응답 (Response)​

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

4.1. 응답 파라미터​

필드명크기(byte)설명
ResultCode4결과코드 (4100: 성공, 이외 실패)
ResultMsg100결과 메세지
TID30거래 아이디
Moid64가맹점 주문번호
Amt12결제 금액
AuthDate12가상계좌 발급 일시 (YYMMDDHHMISS)
VbankBankCode3가상계좌 은행 코드
VbankBankName20가상계좌 은행명
VbankNum20가상계좌번호
VbankExpDate8가상계좌 입금만료일자 (YYYYMMDD)
VbankExpTime6가상계좌 입금만료시간 (HHMISS)

5. 예시​

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

5.1. 요청 예시​

POST /webapi/billing/get_vacount.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded

TID=nictest00m03012608131655309135&MID=nictest00m&Amt=1004&Moid=nicevantest&GoodsName=%B3%AA%C0%CC%BD%BA%C6%E4%C0%CC&BuyerTel=01012345678&BankCode=004&VbankExpDate=20260814235959&CashReceiptType=0&ReceiptTypeNo=&EdiDate=20260813095841&SignData=7949da8236a1edc8b94f027a77bd5c32c3f13a267c3cffa6d7d8b1e0c1270cbc

5.2. 응답 예시​

{
  "ResultCode": "4100",
  "ResultMsg": "가상계좌 발급 성공",
  "TID": "nictest00m03012608131655309135",
  "Moid": "nicevantest",
  "Amt": "000000001004",
  "AuthDate": "260813165841",
  "VbankBankCode": "004",
  "VbankBankName": "국민은행",
  "VbankNum": "48689073649790",
  "VbankExpDate": "20260814",
  "VbankExpTime": "235959"
}