카드상품검색

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', number]
    discountLimit?: {
      amount?: { daily?: number; monthly?: number; yearly?: number }
      count?: { daily?: number; monthly?: number; yearly?: number }
    }
  }[]
  notes?: string[]
}

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

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

{
  "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"
    }
  ]
}

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