무이자 할부 조회 API

카드사별 무이자 할부 프로모션 정보를 조회하기 위한 API입니다.

무이자 할부 조회

카드사 코드(acqCd)를 기준으로, 현재 적용 가능한 무이자 할부 정보를 제공합니다.

안내사항

매입사 기준으로 무이자 할부 정보를 제공합니다.
응답에 포함되는 카드사 목록은 가맹점 설정에 따라 달라질 수 있습니다.
무이자 할부가 설정되지 않은 카드사도 응답에 포함되며, 이 경우 months/partialMonths는 빈 배열, baseAmount는 null, startDate/endDate는 빈 문자열("")로 반환됩니다.

요청 파라미터

POST

/api/v1/promotions/cards/installments

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
	String	2	-	매입사코드 (미입력 시 전체 카드사 정보 조회)
`callHash`	String	-		체크용 해시 데이터 : SHA256(mxId + passKey)

요청 예시

json


{
  "mxId" : "testcorp",
  "acqCd" : "01",
  "callHash" : "SHA256(testcorp6aMoJujE34XnL9gvUqdKGMqs9GzYaNo6)"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`installments`	Object	-	-	무이자 할부 정보
`└ availableMonths`	Array[String]	-	-	전체 할부 가능 개월 (예: "01", "02", ..., "12")
`└ cards`	Array	-	-	카드사별 무이자 할부 정보
	String	2	-	매입사 코드
`└─ acqName`	String	-	-	매입사 명칭
`└─ interestFree`	Object	-	-	무이자 할부 상세
`└── months`	Array[String]	-	-	무이자 할부 개월 리스트 (미설정 시 빈 배열)
`└── partialMonths`	Array[String]	-	-	부분 무이자 할부 개월 리스트 (미설정 시 빈 배열)
`└── baseAmount`	Long	12	-	할부 기준 금액 (원 단위) : 무이자 미설정 카드사는 null
`└── startDate`	String	8	-	무이자 적용 시작일 (YYYYMMDD) : 무이자 미설정 카드사는 빈 문자열
`└── endDate`	String	8	-	무이자 적용 종료일 (YYYYMMDD) : 무이자 미설정 카드사는 빈 문자열

응답 예시

json

{
"code": "0000",
"message": "성공",
"status": "OK",
"requestId": "6a87119e-83b7-45bd-ae86-7714d321eaa6",
"requestAt": "2024-09-27T22:45:54.0173497",
"responseAt": "2024-09-27T22:45:54.1193342",
"data": {
  "mxId": "testcorp",
  "installments": {
    "availableMonths": ["01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12"],
    "cards": [
      {
        "acqCd": "01",
        "acqName": "비씨",
        "interestFree": {
          "months": ["04", "05", "06", "07", "08", "09", "10"],
          "partialMonths": [],
          "baseAmount": 50000,
          "startDate": "20220916",
          "endDate": "99991231"
        }
      },
      {
        "acqCd": "03",
        "acqName": "삼성",
        "interestFree": {
          "months": ["02", "03", "04", "05", "06"],
          "partialMonths": ["10", "11"],
          "baseAmount": 50000,
          "startDate": "20230321",
          "endDate": "99991231"
        }
      },
      {
        "acqCd": "02",
        "acqName": "신한",
        "interestFree": {
          "months": [],
          "partialMonths": [],
          "baseAmount": null,
          "startDate": "",
          "endDate": ""
        }
      }
    ]
  }
}
}

매입사 기준

무이자 할부 정보는 매입사(acqCd) 기준으로 제공됩니다. 동일한 카드라도 매입사에 따라 무이자 할부 조건이 다를 수 있습니다.

기준 금액 확인

무이자 할부가 적용되려면 결제 금액이 baseAmount 이상이어야 합니다. 결제 금액이 기준 금액보다 낮으면 일반 할부로 처리됩니다.

적용 기간

무이자 할부는 startDate부터 endDate까지만 적용됩니다. 프로모션 기간을 확인하여 고객에게 안내하세요. 종료일이 99991231이면 무기한을 의미합니다.