카드상품검색

카드 카탈로그를 카드명 또는 카드사 기준으로 조회합니다.

카드카탈로그

카드상품검색 API의 성공 응답은 CardCatalogSimple[] 배열을 포함한 객체로 반환됩니다.

CardCatalogSimple 객체

interface CardCatalogSearchResponse {
  /**
   * 검색된 카드 카탈로그 목록입니다.
   * 검색 결과가 없으면 빈 배열([])이 반환됩니다.
   */
  data: CardCatalogSimple[]
}

interface CardCatalogSimple {
  /**
   * 카드 카탈로그 ID (UUID)
   */
  id: string

  /**
   * 카드 상품명
   */
  name: string

  /**
   * 카드사 코드
   */
  acquirer: CardCompany

  /**
   * 발급사 기준 카드 상품 참조값
   */
  ref: string

  /**
   * 국내전용 연회비 (원)
   */
  annualFeeDomestic: number

  /**
   * 해외겸용 연회비
   */
  annualFeeInternational: {
    VISA?: number
    MASTER?: number
    JCB?: number
    UNIONPAY?: number
  }

  /**
   * 카드 썸네일 이미지 URL 목록
   */
  thumbnails: string[]

  /**
   * 카드 혜택 목록
   */
  benefits: CardBenefit[]

  /**
   * 카탈로그 최신 갱신 시각 (ISO 8601)
   */
  updatedAt: string
}

interface CardBenefit {
  categoryId?: number
  title?: string
  details?: {
    prevMonthSpendingRange?: [number | null, number | null]
    content?: ['AMOUNT' | 'RATIO' | 'COUNT' | null, number]
    discountLimit?: {
      amount?: { daily?: number; monthly?: number; yearly?: number }
      count?: { daily?: number; monthly?: number; yearly?: number }
    }
  }[]
  notes?: string[]
}

카드상품검색 조회

Request

GET https://api.candypay.co.kr/card-catalogs/search?name=mr%20life

name 또는 acquirer 중 최소 1개를 반드시 전달해야 합니다.

GET https://api.candypay.co.kr/card-catalogs/search?acquirer=SHINHAN

Response

성공

{
  "data": [
    {
      "id": "0194d19d-7b75-7cbf-bf4a-30598e4f2222",
      "name": "신한카드 Mr.Life",
      "acquirer": "SHINHAN",
      "ref": "000123456789",
      "annualFeeDomestic": 15000,
      "annualFeeInternational": {
        "VISA": 18000,
        "MASTER": 18000
      },
      "thumbnails": [
        "https://storage.googleapis.com/static.candypay.co.kr/card_catalog/0194d19d-7b75-7cbf-bf4a-30598e4f2222_0.webp"
      ],
      "benefits": [
        {
          "title": "대중교통 할인"
        }
      ],
      "updatedAt": "2026-02-01T00:00:00.000Z"
    }
  ]
}

카드상품검색에 성공하면 data 배열이 반환됩니다.

실패

name과 acquirer를 모두 생략하면 400 Bad Request가 반환됩니다.

{
  "statusCode": 400,
  "message": "name 또는 acquirer 중 하나는 필수입니다."
}

그 외 실패 응답 형식은 에러 객체를 참고하세요.

동작 참고

• name이 있으면 검색어 정규화 후 유사도 기반으로 정렬됩니다.
• name이 없고 acquirer만 있으면 해당 카드사 카탈로그를 조회합니다.