본문으로 건너뛰기

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

header 파라미터 명세​

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

body 파라미터 요청 명세​

필드명크기(byte)필수설명
usrId20O가맹점관리자페이지 로그인 아이디
encKey256O위변조 검증 데이터, 생성규칙: hex(sha256(sid + usrId + trDtm + MerchantKey))
dt8O조회일자 (YYYYMMDD)
idCl1O조회 권한 구분 (2: MID, 3: GID, 4: AID)
searchID10O조회 권한 구분에 따라 조회할 가맹점 ID

4. 응답 (Response)​

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

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

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

data 하위 파라미터 상세​

필드명크기(byte)설명
id10정산ID
settlmntDt8정산일자
appCnt14입금내역에 포함된 승인건수
appAmt14입금내역에 포함된 승인금액
ccCnt14입금내역에 포함된 취소건수
ccAmt14입금내역에 포함된 취소금액
resrAmt14입금일자에 대한 지급보류 설정 금액
resrCcAmt14입금일자에 대한 지급보류 해제 금액
extraAmt14입금일자에 대한 상계금액
fee14입금내역에 대한 무이자 수수료 포함 전체 수수료
vat14입금내역에 대한 부가세
couponAmt14입금내역에 대한 쿠폰 금액
ninstFee14입금내역에 대한 무이자수수료
depositAmt14입금금액

5. 예시​

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

5.1. 요청 예시​

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

{
  "header": {
    "sid": "0301004",
    "trDtm": "20200312155757",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "idCl": "2",
    "searchID": "nictest00m",
    "dt": "20200117",
    "encKey": "b254a875d11b3ef6708c9d265c32626ba0fa4f4a20314062639e602dcd66c765"
  }
}

5.2. 응답 예시​

{
  "header": {
    "sid": "0301004",
    "trDtm": "20200312155757",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200117",
    "authCl": "2",
    "dataCnt": 1,
    "data": [
      {
        "id": "nictest00m",
        "settlmntDt": "20200117",
        "appCnt": 22,
        "appAmt": 3246689,
        "ccCnt": 0,
        "ccAmt": 0,
        "resrAmt": 3168769,
        "resrCcAmt": 0,
        "extraAmt": 0,
        "fee": 77920,
        "vat": 0,
        "couponAmt": 100,
        "ninstFee": 0,
        "depositAmt": 1590880
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0301004",
        "trDtm": "20200312155757",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "idCl": "2",
        "searchID": "nictest00m",
        "dt": "20200117",
        "encKey": "db6da355a5710eae364144179305890a6fb20c02bd0cf70a8b6b55a4ee7a1b78"
      }
    }
  }
}