현금영수증 발급하기
1. Flow
2. 설명 (Description)
- 금액을 포함한 결제 정보 및 가맹점 정보를 기준으로 현금영수증을 발급하는 서비스입니다.
- 발급 요청 성공 후 다음 날에 국세청으로 전달되며 최종 성공/실패는 관리자페이지 혹은 현금영수증 대사 API를 통해 확인합니다.
- 취소 시 응답된 TID를 사용해야 합니다 (요청 TID로 취소 시 오류).
- 취소가 필요한 경우 발급 당해년도 내 취소를 권장합니다.
3. 요청 (Request)
3.1. HTTP Request
- Method:
POST - URL:
https://webapi.nicepay.co.kr/webapi/cash_receipt.jsp - Content-Type:
application/x-www-form-urlencoded - Encoding:
EUC-KR
3.2. 요청 파라미터
| 필드명 | 크기(byte) | 필수 | 설명 |
|---|---|---|---|
| TID | 30 | O | 거래 아이디, TID 생성규칙 항목 참고 |
| MID | 10 | O | 가맹점 아이디 |
| EdiDate | 14 | O | 전문생성일시 (YYYYMMDDHHMISS) |
| Moid | 64 | O | 가맹점 주문번호 (고유한 값으로 설정, 나이스페이 가공 없음) |
| ReceiptAmt | 12 | O | 현금영수증 발행 금액 |
| GoodsName | 40 | O | 상품명 |
| SignData | 256 | O | 위변조 검증 데이터, 생성 규칙: hex(sha256(MID + ReceiptAmt + EdiDate + Moid + MerchantKey)) |
| ReceiptType | 1 | O | 현금영수증 발급 타입 (1: 소득공제, 2: 지출증빙) |
| ReceiptTypeNo | 20 | O | 현금영수증 발급 번호 ( '-' 없이 숫자만 입력) |
| ReceiptSupplyAmt | 12 | O | 공급가액 (미사용 시 0, 사용 시 협의 필요) |
| ReceiptVAT | 12 | O | 부가세 (미사용 시 0, 사용 시 협의 필요) |
| ReceiptServiceAmt | 12 | O | 봉사료 (미사용 시 0, 사용 시 협의 필요) |
| ReceiptTaxFreeAmt | 12 | O | 면세 (미사용 시 0, 사용 시 협의) |
| ReceiptSubNum | 10 | 서브몰 사업자 번호 | |
| ReceiptSubCoNm | 40 | 서브몰 사업자 상호 | |
| ReceiptSubBossNm | 20 | 서브몰 사업자 대표자 | |
| ReceiptSubTel | 16 | 서브몰 사업자 전화번호 | |
| BuyerName | 30 | 구매자명 | |
| BuyerEmail | 60 | 구매자 이메일 주소 | |
| BuyerTel | 20 | 구매자 전화번호 | |
| CharSet | 10 | 인증 응답 인코딩 (euc-kr(default) / utf-8) | |
| EdiType | 10 | 응답전문 유형 (JSON(default) / KV) *KV:Key=value |
TID 생성규칙
생성 규칙
- MID(10) + 지불수단(2) + 매체구분(2) + 시간정보(12) + 랜덤(4)
- 크기: 30 byte
- 설명:
- MID: 가맹점 아이디 (문자열 끝은 소문자 m으로 기재되어야 함.)
- 지불수단: 결제수단별 코드 (04: 현금영수증)
- 매체구분: 거래 형태 (01: 일반)
- 시간정보: 결제 요청 일시 (YYMMDDHHMISS)
- 랜덤: 거래를 식별하기 위한 임의의 값 4자리
- TID 생성 예시: nictest00m04012605071920282231
현금영수증 발급번호(ReceiptTypeNo) 관련 안내사항
ReceiptTypeNo 입력 시 안내 사항
- ReceiptType 파라미터를
1(소득공제) 로 설정한 경우, 전화번호 또는 주민번호 입력 - ReceiptType 파라미터를
2(지출증빙) 로 설정한 경우, 사업자번호 입력 - 자진발급 요청 시 ReceiptType은
1, ReceiptTypeNo는01000001234입력 필수
현금영수증 옵션 파라미터 안내 사항
현금영수증 금액 설정 관련 안내 사항
- ReceiptSupplyAmt, ReceiptVAT, ReceiptServiceAmt, ReceiptTaxFreeAmt 4개 필드 사용을 희망하는 경우 영업담당자를 통해 사전 협의 및 MID 설정이 필요합니다.
- 미사용 시에는 반드시 각 필드를 0원으로 설정합니다.
- 협의 이후 사용 시에는 4개 필드의 합이 ReceiptAmt 값과 동일해야 합니다.
현금영수증 서브사업자 정보 안내 사항
- 가맹점의 서브 사업자 정보를 현금영수증에 담아야 하는 경우에 사용하는 옵션입니다.
- 영업담당자와 협의 후 MID에 해당 옵션을 사용하도록 설정된 경우에만 사용할 수 있습니다.
- 해당 옵션 사용 중, 사전에 가맹점관리자페이지에 등록한 서브 사업자 정보가 아닌 값으로 요청 시 자동으로 등록 처리됩니다.
4. 응답 (Response)
4.1. 응답 파라미터
PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| ResultCode | 4 | 결과 코드 (7001: 성공, 그 외 실패) |
| ResultMSG | 100 | 결과 메세지 |
| TID | 30 | 현금영수증 TID (요청 TID와 다름) |
| Moid | 64 | 가맹점 주문번호 |
| AuthCode | 30 | 현금영수증 승인번호 |
| AuthDate | 12 | 현금영수증 발급 요청 일자 |
5. 예시
아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.
5.1. 요청 예시
POST /webapi/cash_receipt.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded
MID=nictest00m&TID=nictest00m04012608181159082847&EdiDate=20260818050827&Moid=TEST12346&SignData=f88a4d02d8f6856f194b7a30afb06c74eccd6f0440fe506fb91fb13b37cd382e&GoodsName=Receipttest&ReceiptAmt=1000&ReceiptType=1&ReceiptTypeNo=01091357359&ReceiptSupplyAmt=0&ReceiptVAT=0&ReceiptServiceAmt=0&ReceiptTaxFreeAmt=0&ReceiptSubNum=1234567891&ReceiptSubCoNm=%B3%AA%C0%CC%BD%BA%C1%A4%BA%B8%C5%EB%BD%C5&ReceiptSubBossNm=%C8%AB%B1%E6%B5%BF&ReceiptSubTel=01091357359&CharSet=euc-kr
5.2. 응답 예시
{
"ResultCode": "7001",
"ResultMsg": "현금영수증 처리 성공",
"TID": "nictest00m04012608181208287165",
"Moid": "TEST12346",
"AuthCode": "I72680791",
"AuthDate": "260818120828"
}
6. 발급 취소
- 수동으로 발급한 현금영수증에 대하여 취소 시 결제 취소 페이지를 참조하여 취소 처리합니다.
- 이 때, 취소 요청 시 TID는 현금영수증 요청 시 TID가 아닌 응답 TID 값을 사용해야 합니다.