신개념 결제 플랫폼, KONA PLATE

API 문서

전체 API

서비스

선불카드
체크카드

실물카드 등록동기

버전: v1

POST

/api/v1/prepay-card/physical/register

실물카드를 회원의 App에 등록 처리 합니다. 선불카드를 대상으로 합니다. 실물카드 등록에는 다음의 시나리오가 발생 합니다. ① 선발급 속성의 선불카드 등록 : 모바일카드가 먼저 발급되고 실물카드를 배송 받아 등록하는 경우 입니다. 실물카드를 등록하면 발급된 모바일카드와 연결됩니다. 단, 등록할 실물카드는 거래내역이 없어야 하며, 거래내역이 존재할 경우 ②번의 경우가 됩니다. ② 선발급 속성이 아닌 선불카드 등록 : 선발급 속성의 선불카드가 아닌 경우는 신청 시 모바일카드가 발급되지 않고, 등록 시 모바일카드가 발급되면서 실물카드와 연결되면서 등록이 됩니다. ③ 재발급 신청한 카드에 대한 실물카드 등록 : 선발급 속성의 선불카드를 재발급 신청하였을 경우, 재발급 신청 시 모바일카드가 먼저 발급되고, 잔액이 새로 발급된 모바일카드로 이관되며 실물카드가 배송됩니다. 배송 받은 실물카드를 등록하면 발급된 모바일카드와 연결됩니다. 재발급 신청된 선불카드가 선발급 속성이 아닌 경우에는 실물카드 등록 시 모바일카드가 발급되고, 잔액이 기존 카드에서 새로 발급된 모바일카드로 이관되며 실물카드가 등록됩니다. ④ 체크카드와 연결될 모바일카드에 선불카드 등록 : 체크카드 등록 시 발급된 모바일카드에 실물카드를 연결 합니다. 회원은 연결하고자 원하는 체크카드의 모바일카드를 선택하여 실물카드 등록을 요청할 수 있습니다.

요청 헤더

X-KM-User-AspId

string

필수

길이 : 16

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, ...)

요청 파라미터

암호화 처리|

더 자세한 정보는

가이드라인

을 참조하세요.

cardApplyNo

string

옵션

길이 : 22

카드 신청 번호

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

- 선발급된 모바일카드와 연결을 원할 경우, 해당 데이터를 설정해야 합니다.

- 미 설정 시, 선발급된 모바일카드와 연결 없이 실물카드 등록이 됩니다.

- 재발급 된 카드를 등록하는 경우, 해당 데이터를 설정해야 이전 카드의 잔액이 이관 됩니다.

userId

number

필수

최소 : 1 , 최대 : 9999999999999999999

등록하려는 회원 ID

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

physicalCardNo

string

필수

길이 : 16

등록하려는 (실물카드) 카드 번호

physicalCardExpDate

string

필수

길이 : 4

등록하려는 (실물카드) 카드 사용 유효기간

-형식: YYMM

physicalCardCVC

string

필수

길이 : 3

등록하려는 (실물카드) 카드 인증 코드

tcList

array of objects

조건부

약관 동의 목록

특정 카드의 경우, 카드를 등록할 때, 약관 동의를 받아야 합니다. 이때, 사용자가 동의한 약관의 정보입니다.

추가 object

extMobileCardPar

string

옵션

길이 : 27

연결 할 모바일카드의 카드의 PAN(Primary Account Number)을 대체하는 번호

응답 헤더

X-KM-Correlation-Id

string

필수

길이 : 20

전문 추적을 위한 거래번호

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

X-KM-Crypto-Key-Id

string

옵션

길이 : 32

데이터암복호화 키 ID

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

응답 파라미터

암호화 처리|

더 자세한 정보는

가이드라인

을 참조하세요.

mobileCardNo

string

필수

길이 : 16

회원에게 발급된 모바일 카드 번호

- 사용자가 실물 카드를 등록하게 되면 모바일 카드도 발급 된다.

par

string

필수

길이 : 27

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

응답 코드

Detailed classification and addition of error for unseccessful withfrawal

200

에러 코드

000_000

메시지

Success.

설명

성공

400

에러 코드

003_012

메시지

Indicated card issue is not ready to active.

설명

cardApplyNo로 지정한 카드 신청 건이 카드 등록 가능한 상태가 아닌 경우 발생

400

에러 코드

003_013

메시지

Indicated card issue not found error.

설명

cardApplyNo로 지정한 카드 신청 건이 존재하지 않을 경우 발생

400

에러 코드

003_001

메시지

Invalid card info.

설명

입력한 카드정보(카드번호, 만료일, CVC)가 유효하지 않습니다.

400

에러 코드

003_014

메시지

Digital card is already terminated error.

설명

실물 카드와 연결하려는 모바일 카드가 이미 폐기 상태일 경우 발생

테스트 데이터

200 - 성공 테스트

200 - 성공 테스트 - OPTIONAL parameter 없이 요청

400 - cardApplyNo로 지정한 카드 신청 건이 카드 등록 가능한 상태가 아닌 경우 발생

400 - cardApplyNo로 지정한 카드 신청 건이 존재하지 않을 경우 발생

400 - 입력한 카드정보(카드번호, 만료일, CVC)가 유효하지 않습니다.

400 - 실물 카드와 연결하려는 모바일 카드가 이미 폐기 상태일 경우 발생

400 - 이미 등록 되어있는 카드를 등록하려는 경우 발생

Loading ...

Request

Response

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

회원 가입 회원 정보 조회 회원 비밀번호 재설정 및 변경 회원 정보 변경 회원 탈퇴 회원 로그인 ID 확인 휴면 회원 해제 약관 목록 조회 약관 동의 및 철회 CI 값으로 회원 정보 조회 회원 로그인 ID 중복 확인 회원 비밀번호 검증 회원 인증 정보 조회 금융사 목록 조회 계좌 예금주 실명 검증 ARS 인증 전 인증코드 생성 PG를 통한 은행 계좌 등록 계좌 등록 상태 조회 기명화 및 한도상향(개인)회원 등록 계좌 조회 회원 계좌 정보 조회 자동충전 계좌 등록 회원 계좌 삭제 일회용 토큰 발급 계좌 충전 계좌 충전취소 충전 및 충전취소 결과 확인 거래내역 확인 선불카드 발급 및 배송 신청 카드 신청 취소 선불카드 재발급(교체발급)만료 예정 선불카드 재발급 갱신 카드 배송 상태 조회 실물카드와 연결 가능한 모바일카드 신청 정보 조회 실물카드 등록 보유카드 조회 미등록 카드 조회 카드 상태 변경 카드 폐기 기명화 및 한도상향(개인)기명화 및 한도상향(법인)법인 기명화 여부 조회 소득공제 신청 카드 소득공제 신청 여부 조회 카드 매핑 회원 조회 카드 상품ID로 상품 정보 조회 주카드 설정 카드에 연결된 가상계좌 조회 회원 가입 회원 정보 조회 회원 비밀번호 재설정 및 변경 회원 정보 변경 회원 탈퇴 회원 로그인 ID 확인 휴면 회원 해제 약관 목록 조회 약관 동의 및 철회 CI 값으로 회원 정보 조회 회원 로그인 ID 중복 확인 회원 비밀번호 검증 회원 인증 정보 조회 금융사 목록 조회 계좌 예금주 실명 검증 ARS 인증 전 인증코드 생성 PG를 통한 은행 계좌 등록 계좌 등록 상태 조회 기명화 및 한도상향(개인)회원 등록 계좌 조회 회원 계좌 정보 조회 자동충전 계좌 등록 회원 계좌 삭제