본문으로 건너뛰기

무이자정보조회 API 연동하기

1. 무이자정보조회 API Flow​

2. 설명 (Description)​

  • 카드 할부 결제 시 카드사가 제공하는 무이자 할부개월 정보와 가맹점에서 수수료를 부담하는 할부개월 정보에 대하여 조회할 수 있는 서비스입니다.
  • 카드사에서 제공하는 무이자 할부개월 수는 매월 달라집니다.
  • 가맹점에서는 고객 편의를 위해 특정 할부개월에 할부 수수료를 부담하여 고객이 무이자로 할부 결제를 진행할 수 있도록 설정이 가능합니다. 사용을 원하시는 경우 영업담당자를 통해 사전 협의가 필요합니다.

3. 요청 (Request)​

3.1. HTTP Request​

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

3.2. 요청 전문 구성​

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

header 파라미터 명세​

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

body 파라미터 요청 명세​

필드명크기(byte)필수설명
mid10O가맹점 아이디
encKey256O위변조 검증 데이터, 생성규칙: hex(sha256(sid + mid + trDtm + MerchantKey))
targetDt8O대상일자 (YYYYMMDD)

4. 응답 (Response)​

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

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

필드명크기(byte)설명
mid10가맹점 아이디
targetDt8대상일자 (YYYYMMDD)
dataCnt8데이터 count
data-무이자 정보 Data, 파라미터 상세 정보는 아래 "data 하위 파라미터 상세" 항목 참고

data 하위 파라미터 상세​

필드명크기(byte)설명
fnCd2카드사 코드
fnNm60카드사 이름
instmntMon2할부개월 수
instmntType2할부 유형 (00: 카드사 부담, 01: 가맹점 부담)
minAmt10무이자 할부 적용 최소 금액

5. 예시​

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

5.1. 요청 예시​

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

{
  "header":{
    "sid":"0201001",
    "trDtm":"20200427135523",
    "gubun":"S",
    "resCode":"",
    "resMsg":""
  },
  "body":{
    "mid":"nictest00m",
    "encKey":"37439ef207e3ba5a8d595f820212ef660375a945c820b377d1a84b0389232521",
    "targetDt":"20200427"
  }
}

5.2. 응답 예시​

{
  "header":{
    "sid":"0201001",
    "trDtm":"20200427135523",
    "gubun":"R",
    "resCode":"0000",
    "resMsg":""
  },
  "body":{
    "mid":"nictest00m",
    "targetDt":"20190212",
    "dataCnt":4,
    "data":[
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"02",
      "instmntType":"00",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"03",
      "instmntType":"00",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"04",
      "instmntType":"00",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"05",
      "instmntType":"00",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"06",
      "instmntType":"00",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"07",
      "instmntType":"01",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"08",
      "instmntType":"01",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"09",
      "instmntType":"01",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"10",
      "instmntType":"01",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"11",
      "instmntType":"01",
      "minAmt":50000
      },
      {
      "fnCd":"01",
      "fnNm":"비씨",
      "instmntMon":"12",
      "instmntType":"01",
      "minAmt":50000
      }
    ],
    "reqInfo":{
      "header":{
        "sid":"0201001",
        "trDtm":"20200427135523",
        "gubun":"S",
        "resCode":"",
        "resMsg":""
      },
      "body":{
        "mid":"nictest00m",
        "encKey":" 37439ef207e3ba5a8d595f820212ef660375a945c820b377d1a84b0389232521",
        "targetDt":" 20200427"
      }
    }
  }
}