본문으로 건너뛰기

거래대사 API 연동하기

1. 거래대사 API Flow​

2. 설명 (Description)​

  • 특정 일자에 발생한 거래 내역을 조회하는 API입니다.
  • 시간 및 분 단위로도 조회가 가능하며, 범위는 최대 3시간입니다.

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

header 파라미터 명세​

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

body 파라미터 요청 명세​

필드명크기(byte)필수설명
usrId20O가맹점관리자페이지 로그인 아이디
encKey256O위변조 검증 데이터, 생성규칙: hex(sha256(sid + usrId + trDtm + MerchantKey))
svcCd4O결제수단 구분 (아래 "결제수단 구분" 항목 참조)
trCl1O조회 기준 (0: 동일기간 승인/취소 1건 처리, 1: 승인/취소 개별 생성)
dt8O조회일자 (YYYYMMDD)
frTm6조회 시작 시간 (HHMISS) 조회 시작-종료 시간 범위 지정 시 최대 3시간 설정 가능
toTm6조회 종료 시간 (HHMISS) 조회 시작-종료 시간 범위 지정 시 최대 3시간 설정 가능
idCl1O조회 권한 구분 (2: MID, 3: GID, 4: AID)
searchID10O조회 권한 구분에 따라 조회할 가맹점 ID
결제수단 구분 (거래대사 기준)
  • 01: 신용카드
  • 02: 계좌이체
  • 03: 가상계좌
  • 05: 휴대폰 소액결제
  • 14: 문화상품권
  • 26: 계좌간편결제

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
otid30원거래 ID
cartAppTid30서브 원거래 ID (분할정산 메인 MID인 경우 해당 값은 '' )
goodsNm100상품명
goodsAmt14상품 금액
stateCd2거래 상태 (0: 승인, 1: 매입 전취소, 2: 매입 후취소)
appNo30승인번호 (결제 제휴사에서 부여한 승인번호)
moid64가맹점 주문번호
ccMoid40가맹점 거래 취소 주문번호
subid20서브 ID
fnCd6제휴사 코드
paymentNo32결제수단번호 (카드번호/계좌번호/휴대폰 번호, 마스킹 처리)
couponAmt14쿠폰금액 (신용카드 요청 시에만 응답))
joinType2중계/대행 여부 (0: 중계, 1: 대행)
depositNm20입금자명
partSvcCd4간편결제 서비스 코드

5. 예시​

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

5.1. 요청 예시​

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

{
  "header": {
    "sid": "0301001",
    "trDtm": "20200311141341",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "idCl": "2",
    "searchID": "nictest00m",
    "svcCd": "01",
    "trCl": "0",
    "dt": "20200114",
    "frTm": "132933",
    "toTm": "162932",
    "encKey": "c0dda92741f445fe09e627230c90bc9779b16344c7969e86d8be295cceb6613e"
  }
}

5.2. 응답 예시​

{
  "header": {
    "sid": "0301001",
    "trDtm": "20200311142503",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200114",
    "authCl": "3",
    "dataCnt": 9,
    "data": [
      {
        "appDt": "20200114",
        "appTm": "151906",
        "ccDt": "",
        "ccTm": "",
        "mid": "nictest00m",
        "serviceId": "",
        "tid": "nictest00m01012001141519062671",
        "otid": "nictest00m01012001141519062671",
        "cartAppTid": "",
        "goodsNm": "오늘출발테스트 외 1개",
        "goodsAmt": 4520,
        "stateCd": "0",
        "appNo": "30023153",
        "moid": "5784001",
        "ccMoid": "",
        "subid": "",
        "fnCd": "02",
        "paymentNo": "533774******4037",
        "couponAmt": 0,
        "joinType": "1",
        "depositNm": "",
        "partSvcCd": "0000"
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0301001",
        "trDtm": "20200311141341",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "idCl": "2",
        "searchID": "nictest00m",
        "svcCd": "01",
        "trCl": "0",
        "dt": "20200114",
        "frTm": "132933",
        "toTm": "162932",
        "encKey": "c0dda92741f445fe09e627230c90bc9779b16344c7969e86d8be295cceb6613e"
      }
    }
  }
}