카드 BIN 조회

카드번호 앞자리 BIN 정보를 기준으로 카드 발급사 정보를 조회합니다.

Base URL: https://api.candypay.co.kr/bin-ko/...

BinKoCatalog

BIN 조회 API와 전체 데이터 조회 API의 성공 응답은 BinKoCatalog 객체 또는 BinKoCatalog[] 배열로 반환됩니다.

interface BinKoCatalog {
  /**
   * 카드 BIN
   * 6자리 또는 8자리 문자열입니다.
   */
  bin: string

  /**
   * 카드 종류
   * CRD: 신용카드
   * CHK: 체크카드
   */
  type: 'CRD' | 'CHK'

  /**
   * 발급사 코드
   */
  acquirer: string

  /**
   * 매입사 또는 내부 추론된 카드사 코드
   */
  issuer: string

  /**
   * 카드 표시명
   */
  nickname: string

  /**
   * BIN 정보 최신 반영일
   * yyyy-MM-dd 형식입니다.
   */
  updatedAt: string

  /**
   * KSNet 카드 코드
   */
  _KSNetCode: string
}

단건 BIN 조회

BIN 또는 카드번호를 전달하면 매칭되는 카드 정보를 반환합니다.

Request

bin path parameter는 숫자만 허용되며 최소 6자리 이상이어야 합니다.

GET https://api.candypay.co.kr/bin-ko/bin/53275011

6자리 BIN만 전달해도 조회할 수 있습니다.

GET https://api.candypay.co.kr/bin-ko/bin/532750

Response

성공

{
  "bin": "532750",
  "type": "CRD",
  "acquirer": "HANA",
  "issuer": "TOSSBANK",
  "nickname": "토스뱅크카드",
  "updatedAt": "2021-08-07",
  "_KSNetCode": "10003"
}

카드번호 앞 8자리 기준으로 먼저 조회하고, 없으면 앞 6자리 BIN 기준으로 다시 조회합니다.

실패

숫자가 아닌 값이면 400 Bad Request가 반환됩니다.

{
  "statusCode": 400,
  "message": "BIN 값은 숫자만 포함해야 합니다."
}

6자리 미만이면 400 Bad Request가 반환됩니다.

{
  "statusCode": 400,
  "message": "BIN 값은 최소 6자리 이상이어야 합니다."
}

데이터가 없으면 404 Not Found가 반환됩니다.

{
  "statusCode": 404,
  "message": "데이터베이스에 없는 bin 값입니다. 체크카드 또는 일반 신용카드가 맞나요?"
}

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

전체 데이터 조회

최신 BIN 데이터베이스 전체를 배열로 반환합니다.

Request

GET https://api.candypay.co.kr/bin-ko/json

Response

[
  {
    "bin": "352820",
    "type": "CRD",
    "acquirer": "HYUNDAI",
    "issuer": "HYUNDAI",
    "nickname": "현대카드",
    "updatedAt": "2021-08-07",
    "_KSNetCode": "36721"
  }
]

성공 시 BinKoCatalog[] 배열이 반환됩니다.

Enum 조회

내부에서 사용하는 카드사 enum 맵을 반환합니다.

Request

GET https://api.candypay.co.kr/bin-ko/enums

Response

interface BinKoEnums {
  CardCompany: Record<string, string>
  CardCompanyExtended: Record<string, string>
  CardCompanyGlobal: Record<string, string>
}

{
  "CardCompany": {
    "HANA": "하나카드"
  },
  "CardCompanyExtended": {
    "TOSSBANK": "토스뱅크"
  },
  "CardCompanyGlobal": {
    "VISA": "VISA"
  }
}