빌키 등록 API

빌링 서비스 빌키 등록 Non-UI 방식에서 사용하는 API입니다.

빌키(BillKey)란?

빌키는 고객의 카드 정보를 안전하게 저장하기 위한 토큰입니다.
실제 카드 정보 대신 빌키를 사용하여 정기 결제(빌링 결제)를 진행할 수 있습니다.

RSA 암호화 필수

카드정보를 입력받는 UI는 가맹점에서 구현이 필요하며, RSA 암호화시 사용하는 공개키는 별도 문의가 필요합니다.
카드번호, 신분확인번호, 비밀번호는 반드시 RSA로 암호화하여 전송해야 합니다.

요청 파라미터

POST

/api/v1/bill_reg

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`custNo`	String	64		회원번호 (고객 식별자)
`ccNo`	String	-		카드번호 (RSA 암호화)
`ccExpDate`	String	6		카드유효기간 (YYYYMM)
`ccVfNo`	String	-		신분확인번호 (RSA 암호화) - 생년월일(YYMMDD) or 사업자번호
`ccVfValue`	String	-		비밀번호 (RSA 암호화)
`custName`	String	64		회원명
`phoneNo`	String	32	-	회원 휴대폰번호('-' 제거)
`callHash`	String	-		체크용 해시 데이터 : SHA256(mxId + custNo + passKey)

요청 예시

json

{
  "mxId": "testcorp",
  "custNo": "CustNo001",
  "ccNo": "RSA암호화된카드번호",
  "ccExpDate": "YYYYMM",
  "ccVfNo": "RSA암호화된신분확인번호",
  "ccVfValue": "RSA암호화된비밀번호",
  "custName": "테스터",
  "phoneNo": "01012345678",
  "callHash": "SHA256(mxId + custNo + passKey)"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

필수

조건부 필수

key	타입	최대크기	설명
`mxId`	String	12	가맹점 ID
`billKey`	String	28	빌키 (이후 결제 시 사용)
`custNo`	String	64	회원번호
`custName`	String	64	회원명
	String	2	발급사코드
`ccNo`	String	4	카드번호 뒤 4자리
	String	1	체크카드 여부

보안 주의사항

카드 정보는 절대 평문으로 전송하지 마세요.
RSA 공개키는 KPN에 문의하여 발급받으세요.
원본 카드 정보는 가맹점 서버에 저장하지 마세요. (PCI-DSS 준수)

custNo 관리

custNo는 고객을 식별하는 고유 번호입니다. 동일한 고객에 대해 여러 개의 빌키를 등록할 수 있으며, 각 빌키는 서로 다른 카드를 나타냅니다.
※ 자주 묻는 질문 - 정기결제 ※