카드 즉시할인 조회 API

카드사별 즉시할인 프로모션 정보를 조회하기 위한 API입니다.

카드 즉시할인 조회

카드사 코드(acqCd)를 기준으로, 가맹점에 설정된 즉시할인 정보를 제공합니다. 결제 금액에 따른 필터링은 수행하지 않으므로, 실제 적용 가능 여부는 minAmount와 balanceAmount로 판단해야 합니다.

안내사항

설정된 모든 즉시할인 정보를 제공합니다. balanceAmount가 0보다 크면 사용 가능, 0 이하면 한도 소진으로 사용 불가입니다.
동일한 매입사(acqCd)에 여러 건의 즉시할인이 설정될 수 있습니다. 이 API는 별도 정렬을 적용하지 않으므로 배열의 순서는 보장되지 않습니다. (전체 조회 API는 acqCd 오름차순으로 정렬됩니다.)
즉시할인이 설정되지 않은 가맹점의 경우 빈 배열이 반환됩니다.
매입사 기준으로 프로모션 정보를 제공합니다.

요청 파라미터

POST

/api/v1/promotions/cards/discounts

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
`discounts`	Array	-	-	즉시할인 정보 리스트 (미설정 시 빈 배열, 동일 acqCd 중복 가능)
	String	2	-	매입사 코드
`└ acqName`	String	-	-	매입사 명칭
`└ discountCode`	String	10	-	할인 코드
`└ discountName`	String	-	-	할인명
`└ discountType`	String	1	-	할인 유형 (P: 정률(%), W: 정액(원))
`└ discountAmount`	Long	12	-	할인 값 (정률일 경우 % 값, 정액일 경우 금액(원))
`└ minAmount`	Long	12	-	최소 결제 금액 (원 단위)
`└ maxDiscountAmount`	Long	12	-	최대 할인 금액 (원 단위)
`└ startDate`	String	12	-	할인 적용 시작일시 (YYYYMMDDHHmm)
`└ endDate`	String	12	-	할인 적용 종료일시 (YYYYMMDDHHmm)
`└ balanceAmount`	Long	12	-	잔여 한도 금액 (원 단위) : 0보다 크면 사용 가능, 0 이하면 한도 소진으로 사용 불가

응답 예시

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",
  "discounts": [
    {
      "acqCd": "01",
      "acqName": "비씨",
      "discountCode": "B001",
      "discountName": "비씨카드 2만원 할인",
      "discountType": "W",
      "discountAmount": 20000,
      "minAmount": 30000,
      "maxDiscountAmount": 20000,
      "startDate": "202601260000",
      "endDate": "999901260000",
      "balanceAmount": 100000
    },
    {
      "acqCd": "01",
      "acqName": "비씨",
      "discountCode": "bc130",
      "discountName": "비씨카드 3천원 할인",
      "discountType": "W",
      "discountAmount": 3000,
      "minAmount": 200000,
      "maxDiscountAmount": 3000,
      "startDate": "202607201105",
      "endDate": "202607310000",
      "balanceAmount": 6000000
    },
    {
      "acqCd": "02",
      "acqName": "신한",
      "discountCode": "A002",
      "discountName": "신한카드 10% 할인",
      "discountType": "P",
      "discountAmount": 10,
      "minAmount": 2000,
      "maxDiscountAmount": 4000,
      "startDate": "202601260000",
      "endDate": "999901260000",
      "balanceAmount": 100000
    }
  ]
}
}

가맹점 할인 한도

즉시할인은 가맹점별로 할인 한도(depository)가 설정되어 있습니다. 응답에는 한도가 소진된 쿠폰도 포함되므로, balanceAmount가 0보다 큰지 확인하여 할인 가능 여부를 판단하세요.

할인 유형

P (정률): 결제 금액의 일정 비율을 할인합니다. discountAmount가 10이면 10% 할인입니다.
W (정액): 고정 금액을 할인합니다. discountAmount가 20000이면 20,000원 할인입니다.

최소/최대 금액 확인

minAmount: 해당 금액 이상 결제 시에만 할인이 적용됩니다.
maxDiscountAmount: 정률 할인의 경우에도 최대 할인 금액을 초과할 수 없습니다.
응답은 결제 금액과 무관하게 설정된 쿠폰을 모두 반환하므로, 결제 금액이 minAmount 미만인 쿠폰은 가맹점에서 직접 제외해야 합니다.

적용 기간 형식

즉시할인의 startDate/endDate는 분 단위까지 포함한 YYYYMMDDHHmm 12자리 형식입니다. 무이자 할부 응답의 날짜(YYYYMMDD, 8자리)와 형식이 다르므로 파싱 시 주의하세요. 종료일시가 9999로 시작하면 무기한을 의미합니다.