본문으로 건너뛰기

정산대사 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는 "0301003"를 입력하여야 합니다.
  • body는 전문 id에 대한 요청/응답 값을 정의합니다.

header 파라미터 명세​

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

body 파라미터 요청 명세​

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

4. 응답 (Response)​

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

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

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

data 하위 파라미터 상세​

필드명크기(byte)설명
trDt8거래일자 (YYYYMMDD)
tid30거래 ID
mid10가맹점 ID
serviceId30서비스 ID
subId30서브 가맹점 ID
settlmnDt8정산일자 (YYYYMMDD)
svcCd4결제수단 구분
stateCd2거래 구분
transType2거래 형태 (0: 일반, 1: 에스크로)
trAmt14거래 금액
depositAmt14정산 금액
fee14수수료
vat14부가가치세
instmntMon2할부개월 ("신용카드" 요청 시에만 응답)
ninstFee14무이자 할부 수수료 ("신용카드" 요청 시에만 응답)
fnCd6제휴사 코드
partSvcCd4간편결제코드
moid64가맹점 주문번호

total 하위 파라미터 상세​

필드명크기(byte)설명
appCnt10승인 건수
appAmt14승인 금액
ccCnt10취소 건수
ccAmt34취소 금액
depositAmt14정산 금액
fee14수수료
vat14부가가치세

5. 예시​

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

5.1. 요청 예시​

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

{
  "header": {
    "sid": "0301003",
    "trDtm": "20200311143238",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "idCl": "2",
    "searchID": "nictest00m",
    "svcCd": "01",
    "dtDiv": "0",
    "dt": "20200106",
    "encKey": "aa30a24ffcee915b23fd08ffb42d7b7f80af6826724ef65d6f7ef6f373dc72c8"
  }
}

5.2. 응답 예시​

{
  "header": {
    "sid": "0301003",
    "trDtm": "20200311143238",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200106",
    "authCl": "2",
    "dataCnt": 16,
    "data": [
      {
        "trDt": "20200102",
        "tid": "nictest00m01012001021713090850",
        "mid": "nictest00m",
        "settlmntDt": "20200106",
        "svcCd": "01",
        "stateCd": "0",
        "transType": "0",
        "trAmt": 51004,
        "depositAmt": 49877,
        "fee": 1025,
        "instmntMon": "00",
        "ninstFee": 0,
        "partSvcCd": "0000"
      },
      {
        "trDt": "20200102",
        "tid": "nictest00m01012001021719312312",
        "mid": "nictest00m",
        "settlmntDt": "20200106",
        "svcCd": "01",
        "stateCd": "0",
        "transType": "0",
        "trAmt": 5100,
        "depositAmt": 4988,
        "fee": 112,
        "instmntMon": "00",
        "ninstFee": 0,
        "partSvcCd": "0000"
      },
      ...
    ],
    "total": {
      "appCnt": 16,
      "appAmt": 1201004,
      "ccCnt": 0,
      "ccAmt": 0,
      "depositAmt": 1174454,
      "fee": 24140,
      "vat": 0
    },
    "reqInfo": {
      "header": {
        "sid": "0301003",
        "trDtm": "20200311143238",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "idCl": "2",
        "searchID": "nictest00m",
        "svcCd": "01",
        "dtDiv": "0",
        "dt": "20200106",
        "encKey": "aa30a24ffcee915b23fd08ffb42d7b7f80af6826724ef65d6f7ef6f373dc72c8"
      }
    }
  }
}