빌키 발급 API 연동하기

1. 빌키 발급 API Flow

2. 설명 (Description)

• 빌키 발급 API는 카드번호, 유효기간 등의 카드 정보로 별도의 인증 절차 없이 가맹점과 PG사 사이에서 사용 가능한 고유한 키값을 발급받는 API 입니다.
• 정상 응답된 빌키(BID)는 가맹점에서 관리해야 하며 나이스페이로 빌키 삭제 요청을 하지 않는 경우 요청 시 카드의 유효기간 만료 시까지 사용 가능합니다.
• 1개의 카드로 여러 개의 빌키 생성이 가능하며 정상 발급된 빌키는 모두 사용이 가능합니다.
• 해당 문서에서는 빌키발급 API 요청 시 필요한 기본적인 파라미터 위주로 기재하고 있습니다.
  이외 부가적인 기능을 원하시는 경우 영업담당자를 통해 가능 여부를 협의하시기 바랍니다.

3. 요청 (Request)

3.1. HTTP Request

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

3.2. 요청 파라미터

필드명	크기(byte)	필수	설명
MID	10	O	가맹점 아이디
EdiDate	14	O	전문생성일시 (YYYYMMDDHHMISS)
Moid	64	O	가맹점 주문번호 (고유한 값으로 설정, 나이스페이 가공 없음)
EncData	512	O	결제정보 암호화 데이터, EncData 생성 규칙 및 하위 파라미터 상세 항목 참고
SignData	256	O	위변조 검증 데이터, 생성 규칙: hex(sha256(MID + EdiDate + Moid + MerchantKey))
BuyerEmail	60		구매자 이메일 주소
BuyerTel	20		구매자 전화번호
BuyerName	30		구매자명
CharSet	10		인증 응답 인코딩 (euc-kr(default) / utf-8)
EdiType	10		응답전문 유형 (JSON(default) / KV) *KV:Key=value

EncData 생성 규칙 및 하위 파라미터 상세

생성 규칙

• 암호화 알고리즘: AES128/ECB/PKCS5padding
• 암호화 결과 인코딩: Hex Encoding
• 암호 Key: 가맹점에 부여된 MerchantKey 앞 16자리

결제정보 암호화 생성 규칙: Hex(AES(CardNo=value&ExpYear=YY&ExpMonth=MM&IDNo=value&CardPw=value))

필드명	크기(byte)	필수	설명
CardNo	16	O	카드번호
ExpYear	2	O	카드 유효기간(년) (YY)
ExpMonth	2	O	카드 유효기간(월) (MM)
IDNo	13		생년월일 6자리 또는 사업자등록번호 10자리
CardPw	2		카드 비밀번호 앞 2자리

주의사항

• 입력된 카드 정보가 외부로 노출되지 않도록 주의해야 합니다.
• IDNo , CardPw 필드는 계약 현황에 따라 필수 여부가 결정되므로 계약 시 영업담당자와 협의가 필요합니다.

---

4. 응답 (Response)

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

4.1. 응답 파라미터

필드명	크기(byte)	설명
ResultCode	4	결과코드 (F100: 성공, 이외 실패)
ResultMsg	100	결과 메세지
TID	30	거래 아이디
BID	30	빌키, 가맹점에서 관리하여 승인 요청 시 전달
AuthDate	8	빌키 발급 일자 (YYYYMMDD)
CardCode	20	카드사 코드
CardName	20	카드사명
CardCl	1	카드타입 (0: 신용카드, 1: 체크카드)
AcquCardCode	4	매입 카드사 코드
AcquCardName	20	매입 카드사명

---

5. 예시

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

5.1. 요청 예시

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

MID=nictest04m&Moid=Requesttest&EdiDate=20260813101007&EncData=7b23e8b9e9e144228d4c288fbedb570ec6e6466c9b59a0e1670204550cc1954a6b245826d520e775175e6398bb1802980d9d62d822927726a15fbb7d21c1949b1204cd479bcd2afc55e790b5bc121855&SignData=523c4f98914e3be0d39591bad2abcd0f67d3a8d70f568da0300ed1dda20a0dfe&BuyerName=%C8%AB%B1%E6%B5%BF&BuyerTel=01012345678&BuyerEmail=test%40naver.com

5.2. 응답 예시

{
  "ResultCode": "F100",
  "ResultMsg": "빌키가 정상적으로 생성되었습니다.",
  "BID": "BIKYnictest04m2608131710079669",
  "AuthDate": "20260813",
  "CardCode": "02",
  "CardName": "[KB국민]",
  "TID": "nictest04m01162608131710077360",
  "CardCl": "0",
  "AcquCardCode": "02",
  "AcquCardName": "[KB국민]"
}

---