KPN Logo

카드 프로모션 전체 조회 API

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

카드 프로모션 전체 조회

카드사 코드(acqCd)를 기준으로, 가맹점에 설정된 무이자 할부·즉시할인 정보를 함께 제공합니다. 결제 금액에 따른 필터링은 수행하지 않습니다.

사용 권장 시점

결제 페이지 초기 로딩 시 전체 프로모션 정보가 필요한 경우 이 API를 사용하세요. 무이자 할부와 즉시할인 정보를 한 번의 호출로 조회할 수 있습니다.

안내사항
  • 매입사 기준으로 프로모션 정보를 제공합니다.
  • 즉시할인은 설정된 모든 정보를 제공합니다. balanceAmount가 0보다 크면 사용 가능, 0 이하면 한도 소진으로 사용 불가입니다.
  • 동일한 매입사(acqCd)에 여러 건의 즉시할인이 설정될 수 있습니다. discounts와 installments.cards는 매입사 코드(acqCd) 오름차순으로 정렬되어 반환됩니다.
  • 무이자 할부가 설정되지 않은 카드사도 응답에 포함되며, 이 경우 months/partialMonths는 빈 배열, baseAmount는 null, startDate/endDate는 빈 문자열("")로 반환됩니다.

요청 파라미터

POST
/api/v1/promotions/cards
Base URLhttps://dev.firstpay.co.kr
Content-Typeapplication/json
필수
조건부 필수
key타입최대크기필수설명
mxIdString12가맹점 ID
String2-매입사코드 (미입력 시 전체 카드사 정보 조회)
callHashString-체크용 해시 데이터 : SHA256(mxId + passKey)

요청 예시

json

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

응답 파라미터

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

필수
조건부 필수
key타입최대크기필수설명
mxIdString12가맹점 ID
installmentsObject-무이자 할부 정보
└ availableMonthsArray[String]--전체 할부 가능 개월 (예: "01", "02", ..., "12")
└ cardsArray--카드사별 무이자 할부 정보
String2-매입사 코드
└─ acqNameString--매입사 명칭
└─ interestFreeObject--무이자 할부 상세
└── monthsArray[String]--무이자 할부 개월 리스트 (미설정 시 빈 배열)
└── partialMonthsArray[String]--부분 무이자 할부 개월 리스트 (미설정 시 빈 배열)
└── baseAmountLong12-할부 기준 금액 (원 단위) : 무이자 미설정 카드사는 null
└── startDateString8-무이자 적용 시작일 (YYYYMMDD) : 무이자 미설정 카드사는 빈 문자열
└── endDateString8-무이자 적용 종료일 (YYYYMMDD) : 무이자 미설정 카드사는 빈 문자열
discountsArray--즉시할인 정보 리스트 (미설정 시 빈 배열, 동일 acqCd 중복 가능)
String2-매입사 코드
└ acqNameString--매입사 명칭
└ discountCodeString10-할인 코드
└ discountNameString--할인명
└ discountTypeString1-할인 유형 (P: 정률(%), W: 정액(원))
└ discountAmountLong12-할인 값 (정률일 경우 % 값, 정액일 경우 금액(원))
└ minAmountLong12-최소 결제 금액 (원 단위)
└ maxDiscountAmountLong12-최대 할인 금액 (원 단위)
└ startDateString12-할인 적용 시작일시 (YYYYMMDDHHmm)
└ endDateString12-할인 적용 종료일시 (YYYYMMDDHHmm)
└ balanceAmountLong12-잔여 한도 금액 (원 단위) : 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",
  "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": "02",
        "acqName": "신한",
        "interestFree": {
          "months": [],
          "partialMonths": [],
          "baseAmount": null,
          "startDate": "",
          "endDate": ""
        }
      }
    ]
  },
  "discounts": [
    {
      "acqCd": "01",
      "acqName": "비씨",
      "discountCode": "B001",
      "discountName": "비씨카드 2만원 할인",
      "discountType": "W",
      "discountAmount": 20000,
      "minAmount": 30000,
      "maxDiscountAmount": 20000,
      "startDate": "202601260000",
      "endDate": "999901260000",
      "balanceAmount": 100000
    },
    {
      "acqCd": "02",
      "acqName": "신한",
      "discountCode": "A002",
      "discountName": "신한카드 10% 할인",
      "discountType": "P",
      "discountAmount": 10,
      "minAmount": 2000,
      "maxDiscountAmount": 4000,
      "startDate": "202601260000",
      "endDate": "999901260000",
      "balanceAmount": 100000
    }
  ]
}
}

주의사항

API 선택 가이드
매입사 기준

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

날짜 형식이 서로 다릅니다

무이자 할부의 startDate/endDate는 YYYYMMDD(8자리)이고, 즉시할인의 startDate/endDate는 분 단위까지 포함한 YYYYMMDDHHmm(12자리)입니다. 같은 응답 안에 두 형식이 함께 오므로 파싱 시 주의하세요.

프로모션 적용 우선순위

무이자 할부와 즉시할인은 동시에 적용될 수 있습니다. 단, 가맹점 정책에 따라 중복 적용이 제한될 수 있으니 사전에 확인하세요.