본문으로 건너뛰기

현금영수증 대사 API 연동하기

1. 현금영수증 대사 API Flow​

2. 설명 (Description)​

  • 특정 일자에 발급 요청된 현금영수증 내역을 조회하는 API입니다.

3. 요청 (Request)​

3.1. HTTP Request​

  • Method: POST
  • URL: https://data.nicepay.co.kr/recon/api
  • Content-Type: application/json
  • Encoding: UTF-8

3.2. 요청 전문 구성​

  • API 데이터 포맷은 요청 전문을 정의한 header와 전달 파라미터를 정의한 body를 조합한 JSON 데이터입니다.
  • header는 요청 전문ID(sid) 및 결과 코드를 정의합니다.
    • 현금영수증 대사 요청 시 sid는 "0301002"를 입력하여야 합니다.
  • body는 전문 id에 대한 요청/응답 값을 정의합니다.

header 파라미터 명세​

필드명크기(byte)필수설명
sid10O전문 ID, 업무별 정의된 ID 입력 (현금영수증 대사: 0301002)
trDtm14O요청 전문 생성 일시(YYYYMMDDHHMISS)
gubun1O전문 구분 (S: 요청, R: 응답)
resCode4O결과 코드, 빈 값으로 요청 후 결과 코드 반환 (0000: 성공 / 이외 실패)
resMsg255O결과 메세지, 빈 값으로 요청 후 결과 메세지 반환

body 파라미터 요청 명세​

필드명크기(byte)필수설명
usrId20O가맹점관리자페이지 로그인 아이디
encKey256O위변조 검증 데이터, 생성규칙: hex(sha256(sid + usrId + trDtm + MerchantKey))
dt8O조회일자 (YYYYMMDD)
orgSvcCd2O원거래 결제 수단 구분 (아래 "결제수단 구분" 항목 참조)
idCl1O조회 권한 구분 (2: MID, 3: GID, 4: AID)
searchID10O조회 권한 구분에 따라 조회할 가맹점 ID
결제수단 구분 (현금영수증 대사 기준)
  • 01: 신용카드
  • 02: 계좌이체
  • 03: 가상계좌
  • 04: 현금영수증
  • 26: CMS계좌간편결제

4. 응답 (Response)​

4.1. body 파라미터 응답 명세​

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

필드명크기(byte)설명
reqDt8조회 요청일자 (YYYYMMDD)
authCl2사용자 ID별 조회 권한 표기 (2: MID, 3: GID, 4: AID)
dataCnt-데이터 count
data-현금영수증 대사 Data, 파라미터 상세 정보는 아래 "data 하위 파라미터 상세" 항목 참고

data 하위 파라미터 상세​

필드명크기(byte)설명
appDt8승인일자 (YYYYMMDD)
appTm6승인시간 (HHMISS)
ccDt8취소일자 (YYYYMMDD)
ccTm6취소시간 (HHMISS)
mid10가맹점 ID
serviceId30서비스 ID (기존 올더게이트 상점에 한함)
tid30거래 ID
orgTid30원거래 ID
orgSvcCd4원거래 결제수단
goodsNm100상품명
goodsAmt14상품 금액
stateCd2거래 상태 (0: 승인, 1: 취소)
appNo14현금영수증 승인번호
ccNo14현금영수증 취소번호
ordNm14구매자명
Identity14발행번호
status2현금영수증 발급 진행 상태, 아래 "현금영수증 발급 진행 상태 코드" 항목 참조
reqFlg2용도 구분 (1: 소득공제, 2: 지출증빙)
coNm40서브몰명
coNo10서브몰 사업자번호
moid64가맹점 주문번호
현금영수증 발급 진행 상태(status) 코드
  • 0: 성공
  • 1: 요청
  • 2: 요청취소
  • 3: 요청완료
  • 4: 발급완료
  • 9: 요청실패
  • 10: 발급실패

5. 예시​

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

5.1. 요청 예시​

POST /recon/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0301002",
    "trDtm": "20200311142714",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "idCl": "2",
    "searchID": "nictest00m",
    "orgSvcCd": "04",
    "svcCd": "04",
    "trCl": "0",
    "dt": "20200226",
    "encKey": "59710816698fea06cd30d4130c58c7732f1ab0035b0d7ea4a998fbfd2526a6eb"
  }
}

5.2. 응답 예시​

{
  "header": {
    "sid": "0301002",
    "trDtm": "20200311143019",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200226",
    "authCl": "3",
    "dataCnt": 4,
    "data": [
      {
        "appDt": "20200226",
        "appTm": "141309",
        "ccDt": "",
        "ccTm": "",
        "mid": "nictest00m",
        "serviceId": "",
        "tid": "nictest00m04012002261413091092",
        "orgSvcCd": "04",
        "otid": "",
        "goodsNm": "현금영수증발급상품",
        "goodsAmt": 1004,
        "stateCd": "0",
        "appNo": "",
        "ccNo": "",
        "ordNm": "",
        "identity": "010981*****",
        "status": "9",
        "reqFlg": "1",
        "coNm": "",
        "coNo": "",
        "moid": "moid1234567890"
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0301002",
        "trDtm": "20200311142714",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "idCl": "2",
        "searchID": "nictest00m",
        "orgSvcCd": "04",
        "svcCd": "04",
        "trCl": "0",
        "dt": "20200226",
        "encKey": "59710816698fea06cd30d4130c58c7732f1ab0035b0d7ea4a998fbfd2526a6eb"
      }
    }
  }
}