카드빌링 API 연동하기
1. 카드빌링 API Flow
2. 설명 (Description)
- 카드빌링 API는 발급된 BID(빌키)로 💳 결제(승인)를 진행하는 서비스입니다.
- 발급된 빌키를 통해 billing_approve.jsp API를 호출하면 결제(승인) 처리가 완료됩니다.
- 나이스페이에 등록되지 않거나 이미 삭제된 빌키는 결제가 불가합니다.
3. 요청 (Request)
3.1. HTTP Request
- Method:
POST - URL:
https://webapi.nicepay.co.kr/webapi/billing/billing_approve.jsp - Content-Type:
application/x-www-form-urlencoded - Encoding:
EUC-KR
3.2. 요청 파라미터
| 필드명 | 크기(byte) | 필수 | 설명 |
|---|---|---|---|
| BID | 30 | O | 결제 요청할 빌키 |
| TID | 30 | O | 거래 아이디, TID 생성규칙 항목 참고 |
| MID | 10 | O | 가맹점 아이디 |
| EdiDate | 14 | O | 전문생성일시 (YYYYMMDDHHMISS) |
| Moid | 64 | O | 가맹점 주문번호, (고유한 값으로 설정, 나이스페이 가공 없음) |
| Amt | 12 | O | 결제 금액 |
| GoodsName | 40 | O | 상품명 |
| SignData | 256 | O | 위변조 검증 데이터, 생성 규칙: hex(sha256(MID + EdiDate + Moid + Amt + BID + MerchantKey)) |
| CardInterest | 1 | O | 가맹점 분담 무이자 할부 이벤트 사용 여부 (0: 미사용, 1: 사용(무이자)) |
| CardQuota | 2 | O | 할부 개월 (00: 일시불, 02: 2개월, 03: 3개월, ...) |
| BuyerEmail | 60 | 구매자 이메일 주소 | |
| BuyerTel | 20 | 구매자 전화번호 | |
| BuyerName | 30 | 구매자명 | |
| CharSet | 10 | 인증 응답 인코딩 (euc-kr(default) / utf-8) | |
| EdiType | 10 | 응답전문 유형 (JSON(default) / KV) *KV:Key=value | |
| MallReserved | 500 | 가맹점 여분필드 (나이스페이 가공 없음) |
TID 생성규칙
생성 규칙
- MID(10) + 지불수단(2) + 매체구분(2) + 시간정보(12) + 랜덤(4)
- 크기: 30 byte
- 설명:
- MID: 가맹점 아이디 (문자열 끝은 소문자 m으로 기재되어야 함.)
- 지불수단: 결제수단별 코드 (01: 신용카드)
- 매체구분: 거래 형태 (16: 빌링)
- 시간정보: 결제 요청 일시 (YYMMDDHHMISS)
- 랜덤: 거래를 식별하기 위한 임의의 값 4자리
- TID 생성 예시: nictest00m01162605061948280471
4. 응답 (Response)
PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.
4.1. 응답 파라미터
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| ResultCode | 4 | 결과코드 (3001: 성공, 이외 실패) |
| ResultMsg | 100 | 결과 메세지 |
| TID | 30 | 거래 아이디 |
| Moid | 64 | 가맹점 주문번호 |
| Amt | 12 | 결제 금액 |
| AuthCode | 30 | 승인번호 |
| AuthDate | 12 | 승인 일시 (YYMMDDHHMISS) |
| AcquCardCode | 4 | 매입 카드사 코드 |
| AcquCardName | 20 | 매입 카드사명 |
| CardNo | 20 | 카드번호, 예) 12345678****1234 |
| CardCode | 4 | 카드사 코드 |
| CardName | 20 | 카드사명 |
| CardQuota | 2 | 할부개월 |
| CardCl | 1 | 카드타입 (0: 신용카드, 1: 체크카드) |
| CcPartCl | 1 | 부분취소 가능 여부 (0: 불가능, 1: 가능) |
| CardInterest | 1 | 무이자 결제 여부 (0: 이자, 1: 무이자) |
| MallReserved | 500 | 가맹점 여분필드 (요청 시 Data 그대로 전달) |
5. 예시
아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.
5.1. 요청 예시
POST /webapi/billing/billing_approve.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded
TID=nictest04m01162608131740309135&BID=BIKYnictest04m2608131710079669&MID=nictest04m&Amt=1004&Moid=test123456&GoodsName=%B3%AA%C0%CC%BD%BA%C6%E4%C0%CC&CardInterest=0&CardQuota=00&EdiDate=20260813104030&SignData=0fc645fdc31f4ff9de37c6f25d2c8738d543aad9f5924eef40dcf174d853a676&BuyerName=%C8%AB%B1%E6%B5%BF&BuyerTel=01012345678&BuyerEmail=test%40naver.com
5.2. 응답 예시
{"ResultCode":"3001","ResultMsg":"카드 결제 성공","AuthCode":"30042096","AuthDate":"260813174031","AcquCardCode":"02","AcquCardName":"KB국민","CardCode":"02","CardName":"KB국민","CardQuota":"00","CardInterest":"0","CardCl":"0","Amt":"000000001004","Moid":"test123456","TID":"nictest04m01162608131740309135","MsgSource":"PG","GoodsName":"나이스페이","MID":"nictest04m","BuyerName":"홍길동","CcPartCl":"1","MallReserved":"","CardNo":"12345678****3456"}