Konaplate logo

API 문서

전체 API

서비스


보유카드 조회동기

버전: v1


버전: v1

POST

/api/v1/user/card/list

회원이 보유한 카드의 목록과 카드 정보를 아래와 같이 제공합니다. - 카드 상품 정보 - 잔액 정보 - 유효 기간 - 카드 상태 - 카드 번호 - 결제 한도 - 포인트 - 연결 계좌(직불카드인 경우)

요청 헤더


X-KM-User-AspId

string

필수

길이 : 15

ASP ID

  • 서비스 사업자에게 부여한 ID입니다.
  • ID는 계약 시 제공됩니다.

X-KM-Correlation-Id

string

필수

길이 : 20

전문 추적을 위한 거래번호

  • 형식 : yyMMddHHmiSS-xxxxxxx
  • xxxxxxx : 7자리, Hex String

X-KM-Access-Key

string

조건부

길이 : 40

프로젝트에서 생성된 Access Key

  • Callback API 인 경우는 제외합니다.

X-KM-Crypto-Key-Id

string

옵션

길이 : 32

데이터암복호화 키 ID

  • 서비스 사업자의 프로젝트에서 생성 시 부여한 ID입니다
  • 데이터 암호화 요청 시 필수 입력값입니다. (Data Encryption = Y)

X-KM-Tran-Token

string

필수

길이 : 66

공통 Header 정보 - X-KM-Tran-Token

X-KM-Tran-Time

string

필수

길이 : 14

클라이언트 요청 시간

  • 형식 : YYYYMMDDHHMMSS

X-KM-Time-Zone

string

필수

길이 : 3

시간대 정보 (UTC, KST, ...)

요청 파라미터


userId

number

필수

최소 : 1 , 최대 : 9999999999999999999

회원 ID

  • 회원가입 시 부여되는 회원의 고유 ID입니다.

par

string

옵션

길이 : 27

조회할 카드의 카드의 PAN(Primary Account Number)을 대체하는 번호

해당 카드의 정보 만을 조회할 경우에 사용합니다.

physicalCardNo

string

옵션

길이 : 16

조회할 카드의 (실물카드)카드 번호

응답 헤더


X-KM-Correlation-Id

string

필수

길이 : 20

전문 추적을 위한 거래번호

  • 형식 : yyMMddHHmiSS-xxxxxxx
  • xxxxxxx : 7자리, Hex String

X-KM-Crypto-Key-Id

string

옵션

길이 : 32

데이터암복호화 키 ID

  • 서비스 사업자의 프로젝트에서 생성 시 부여한 ID입니다
  • Callback으로 전달될 경우 서비스 사업자에게 발급된 키 중 가장 먼저 발급된 키를 사용 합니다.

응답 파라미터

암호화 처리|
더 자세한 정보는
가이드라인
을 참조하세요.

cardDataInfo

array of objects

필수

카드 정보 목록
 

cardDataInfo_item

object

옵션

cardDataInfo_item content

par

string

필수

길이 : 27

카드의 PAN(Primary Account Number)을 대체하는 번호

limits

object

옵션

결제 한도 정보

직불카드인 경우에만 응답데이터에 포함됩니다.


day

number

옵션

최소 : 0 , 최대 : 9999999999

일 결제 한도

once

number

옵션

최소 : 0 , 최대 : 9999999999

1회 결제 한도

month

number

옵션

최소 : 0 , 최대 : 9999999999

월 결제 한도

balance

number

필수

최소 : 0 , 최대 : 9999999999

카드에 충전되어 있는 잔액 정보

pendingAmount

number

필수

최소 : 0 , 최대 : 9999999999

충전 대기금 금액

  • 카드의 한도를 초과하는 충전 요청이 접수되어, 아직 처리되지 않고 충전 대기 중인 금액.

isNamed

boolean

필수

카드 기명화 여부

  • 기명화란? 무기명으로 발행된 카드를 선불전자지급수단을 법에서 정하는 '실지명의 인증' 또는 '예금계좌와 연결하는 방식'을 통하여 해당 선불전자지급수단의 이용자로 특정하는 행위를 말합니다.

bankInfo

object

옵션

직불카드에 연결된 계좌 정보

직불카드인 경우에만 응답데이터에 포함됩니다.


bankName

string

필수

최소 : 1 , 최대 : 10

은행 이름

accountNo

string

필수

최소 : 1 , 최대 : 20

은행 계좌 번호

enableFIC

boolean

필수

현금IC 포함 여부

  • true : 현금IC 포함
  • false : 현금IC 미포함

직불카드인 경우에만 응답데이터에 포함됩니다.

serviceId

string

필수

길이 : 15

카드 상품 ID

  • 카드 상품에 부여한 고유 식별 값입니다.

expiryDate

string

필수

길이 : 8

카드 사용 유효기간

  • 형식 : yyyyMMdd

refundable

boolean

필수

카드의 환불 가능 여부

remittable

boolean

필수

카드의 송금 가능 여부

아래 항목에 대한 잔액 송금 가능 여부를 설정합니다.

  • 휴대 전화번호로 송금
  • 카드번호로 송금

cardApplyNo

string

옵션

길이 : 22

카드 신청 번호

  • (회원) 모바일 카드 또는 실물 카드를 발급/배송 신청할때 생성되는 고유 번호

serviceName

string

필수

최소 : 1 , 최대 : 255

카드 상품명

mobileCardNo

string

옵션

길이 : 16

(모바일카드) 카드 번호

rechargeable

boolean

필수

카드의 충전 가능 여부

아래 항목의 충전 가능여부를 설정합니다.

  • OFFLINE 단말기 충전
  • 개인계좌 충전
  • 포탈을 통한 ADMIN 충전

cardPointInfo

array of objects

옵션

카드 포인트 정보

cardPointInfo_item

object

옵션

cardPointInfo_item content

autoUse

boolean

필수

포인트 자동사용 여부

  • 포인트 정책에 설정된 값

pointName

string

필수

최소 : 1 , 최대 : 255

포인트 정책명

pointPolicyId

string

필수

길이 : 15

포인트 정책 ID

remainingPoint

number

옵션

최소 : 0 , 최대 : 9999999999

(회원) 포인트 잔액

  • 회원이 가지고 있는 포인트의 잔액

physicalCardNo

string

옵션

길이 : 16

(실물카드) 카드 번호

serviceImageUrl

string

필수

최소 : 1 , 최대 : 255

카드 상품의 이미지 파일 URL

autoReloadStatus

string

옵션

최소 : 1 , 최대 : 8

카드의 자동충전 상태

  • ACTIVE : 활성화
  • INACTIVE : 비활성화
  • NONE : 설정안함

mobileCardStatus

string

옵션

최소 : 1 , 최대 : 7

(모바일카드) 카드의 상태

  • ACTIVE : 정상
  • SUSPENDED : 중지

minRechargeAmount

number

필수

최소 : 0 , 최대 : 9999999999

카드에 충전시 최소 충전금액

physicalCardStatus

string

옵션

최소 : 1 , 최대 : 7

(실물카드) 카드의 상태

  • ACTIVE : 정상
  • SUSPENDED : 중지

rechargeableAmount

number

필수

최소 : 0 , 최대 : 9999999999

카드에 충전 가능한 금액

  • 무기명 카드의 경우 = 무기명카드 최대 충전금액(maxNonRealNameRechargeAmount) - 카드잔액(balance)
  • 기명화된 카드의 경우 = 기명화카드 최대 충전금액(maxRealNameRechargeAmount) - 카드잔액(balance)

 

충전 가능 금액(예)

  • maxNonRealNameRechargeAmount = 500000
  • maxRealNameRechargeAmount = 2000000
  • balance = 300000

무기명 카드인 경우 = 200000(500000 - 300000)

기명화된 카드인 경우 = 1700000(2000000 - 300000)

personalRechargeable

boolean

필수

카드의 개인계좌를 통한 충전 가능 여부

maxRealNameRechargeAmount

number

필수

최소 : 0 , 최대 : 9999999999

기명화된 카드에 충전할 수 있는 최대 금액

maxNonRealNameRechargeAmount

number

필수

최소 : 0 , 최대 : 9999999999

무기명 카드에 충전할 수 있는 최대 금액

rechargeUnitAmt

number

옵션

최소 : 0 , 최대 : 9999999999

충전 단위 설정

cardBizStatus

string

필수

길이 : 2

카드상태 코드

  • 31: 카드 분실로 인한 정지 
  • 36: 카드 수령 전 정지
  • 3A: 카드 재발급으로 인한 중지
  • 60: 정상
  • 61: 카드 분실 신고 해지
  • 35: 카드 유효 기간 만료로 인한 중지

accTransferStatus

string

필수

길이 : 1

모든 이체 진행상태 (충전취소, 환불이체 진행 상태)

  • 0 : 해당 없음
  • 1 : 이체 진행중

enableVirtualAccountPendingAmount

boolean

필수

가상계좌 충전 대기금 사용 여부

virtualAccountMaxPendingAmount

number

필수

최소 : 0 , 최대 : 9999999999

가상계좌 충전 대기금 최대 금액

  • 카드 잔액 + 충전 대기금 잔액의 최대 허용 금액

응답 코드

Detailed classification and addition of error for unseccessful withfrawal


200

에러 코드

000_000

메시지

Success.

설명

성공


400

에러 코드

000_002

메시지

Invalid input parameter. userId

설명

입력 파라미터 오류입니다.


400

에러 코드

000_003

메시지

Missing required values. userId

설명

필수 파라미터가 누락되었습니다.


400

에러 코드

001_006

메시지

Wallet user not found.

설명

회원이 아니거나 탈퇴한 회원입니다.

테스트 데이터

200 - 성공 테스트


200 - 성공 테스트
200 - 성공 테스트_보유카드가 없는 경우
400 - 입력 파라미터 오류입니다.
400 - 필수 파라미터가 누락되었습니다.
400 - 회원이 아니거나 탈퇴한 회원입니다.
200 - 성공 테스트_PAR 파라미터 사용 케이스
200 - 성공 테스트_cardNo 파라미터 사용 케이스
Loading ...

Request

Loading...

Response

Try It!을 클릭하여
입력한 Request의 Response를 확인하세요.


회원 가입회원 정보 조회회원 비밀번호 재설정 및 변경회원 정보 변경회원 탈퇴회원 로그인 ID 확인휴면 회원 해제약관 목록 조회약관 동의 및 철회CI 값으로 회원 정보 조회회원 로그인 ID 중복 확인회원 비밀번호 검증회원 인증 정보 조회금융사 목록 조회계좌 예금주 실명 검증ARS 인증 전 인증코드 생성PG를 통한 은행 계좌 등록계좌 등록 상태 조회기명화 및 한도상향(개인)회원 등록 계좌 조회회원 계좌 정보 조회자동충전 계좌 등록회원 계좌 삭제계좌 1원 인증 요청계좌 1원 인증 코드 검증선불카드 발급 및 배송 신청카드 신청 취소선불카드 재발급(교체발급)만료 예정 선불카드 재발급 갱신카드 배송 상태 조회실물카드와 연결 가능한 모바일카드 신청 정보 조회실물카드 등록보유카드 조회미등록 카드 조회카드 상태 변경카드 폐기기명화 및 한도상향(개인)기명화 및 한도상향(법인)법인 기명화 여부 조회소득공제 신청카드 소득공제 신청 여부 조회카드 매핑 회원 조회카드 상품ID로 상품 정보 조회주카드 설정카드에 연결된 가상계좌 조회직불카드 발급 및 배송 신청카드 신청 취소카드 배송 상태 조회실물카드 등록보유카드 조회카드 상태 변경카드 한도 변경카드 폐기소득공제 신청카드 소득공제 신청 여부 조회주카드 설정일회용 토큰 발급계좌 충전계좌 충전취소충전 및 충전취소 결과 확인거래내역 확인기준 하한 및 월정액 자동 충전 활성화기준 하한 자동 충전 등록기준 하한 및 월정액 자동 충전 목록 조회기준 하한 자동 충전 수정월 정액 자동 충전 등록월 정액 자동 충전 수정기준 하한 및 월정액 자동 충전 등록 해제결제 시 자동 충전 등록결제 시 자동 충전 등록 해제결제 시 자동 충전 목록 조회일회용 토큰 발급환불 수수료 조회환불환불 결과 확인시스템 충전(예치금)시스템 충전 취소(예치금)시스템 환불(예치금)시스템 부분환불(예치금)신용카드 충전 거래 생성신용카드 충전 취소 요청편의점 충전/출금 요청예치금 내역 조회예치금 잔액 조회일회용 토큰 발급결제결제취소결제 망취소거래내역 확인포인트 거래내역 확인보유카드 조회포인트 사용예약 및 취소포인트 거래내역 확인관리자 포인트 지급관리자 포인트 환수스탬프카드 적립이력조회보유 스탬프카드 목록 조회보유 마일리지카드 목록 조회마일리지카드 적립이력조회카드로 송금 전송카드로 송금 수신카드로 송금 거절카드로 송금 취소ATM 출금용 일회용 Token 발급ATM 출금 예약ATM 출금 예약 취소ATM 출금 정보 조회선불카드 선물하기선불카드 선물하기 취소선불카드 선물하기 유효성 검증선불카드 선물하기 수락선불카드 선물하기 거절받은 카드/쿠폰 선물 목록 조회보낸 카드/쿠폰 선물 목록 조회카드 선물 수락 V2카드 선물하기 V2카드 잔액 이관잔액 이관 카드 정보 조회현금영수증 발행 요청현금영수증 발행 취소현금영수증 국세청 승인오류 요청현금영수증 식별 정보 등록현금영수증 식별 정보 조회현금영수증 식별 정보 삭제현금영수증 가맹점 등록현금영수증 가맹점 수정가맹점 그룹 생성가맹점 그룹 수정가맹점 그룹 조회가맹점 정보 조회가맹점 그룹 내 가맹점 추가가맹점 그룹 내 가맹점 삭제신용카드 자동충전 설정(기준 하한)신용카드 자동충전 설정(월정액)신용카드 자동충전 활성화신용카드 자동충전 목록 조회신용카드 자동충전 설정 해제신용카드 자동 충전 설정 변경카드 상품 전체 조회 (관리자용)카드 상품 상세 조회 (관리자용)발급 카드 목록 조회 (관리자용)카드 상품 생성 API (관리자용)카드 선물 내역 조회 (관리자용)