헥토파이낸셜 개발자센터

신용카드 카드등록 (빌키발급 결제창)

결제창에서 0원 인증으로 실제 결제 없이 카드를 등록하고, 정기결제용 빌키(BillKey)를 발급받습니다.

테스트용 키 정보

API 정보

POST/card/cardAuth.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbnpg.settlebank.co.kr/card/cardAuth.do
운영https://npg.settlebank.co.kr/card/cardAuth.do

주의 사항

NOTE

빌키 서비스 신청 안내

신용카드 빌키(billKey)를 내려받고자 하는 경우, 빌키 서비스를 영업 담당자를 통해 별도 신청해야 합니다.
  • 카드 인증만 수행하는 0원 인증 방식으로, 실제 결제(승인)는 발생하지 않습니다. 거래금액(trdAmt)은 "0" 고정입니다.
  • 발급받은 빌키로 2회차 결제 API를 요청하면 됩니다. (신용카드 빌키 결제 API 참고)
  • 결제와 동시에 빌키를 발급받으려면 신용카드 표준 결제창을 사용하세요.

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

필수 파라미터

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└methodAN(20)영문+숫자, 최대 20byte*
PG 서비스에 해당하는 결제 구분 코드
*고정값
└trdDtN(8)숫자, 최대 8byte*
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HH24MISS)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtNameAHN(100)영문+한글+숫자, 최대 100byte*
상점한글명
└mchtENameAN(100)영문+숫자, 최대 100byte*
상점영문명
└pmtPrdtNmAHN(128)영문+한글+숫자, 최대 128byte*
결제상품명
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액. 0원 인증 방식이므로 0 고정
*고정값
└notiUrlAN(250)영문+숫자, 최대 250byte*
카드등록 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
└nextUrlAN(250)영문+숫자, 최대 250byte*
카드등록 결과 화면으로 전환되는 URL
*결제창 내 버튼 클릭 시 리다이렉트 됩니다. outStatCd 값으로 성공(0021)/실패(0031) 여부를 확인하세요.
└cancUrlAN(250)영문+숫자, 최대 250byte*
고객이 결제창의 X 버튼 클릭 시 리다이렉트 되는 URL
*브라우저 종료, 뒤로가기 등은 감지되지 않습니다.
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt(평문) + hashKey

선택 파라미터

└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객명
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
상점에서 보내주는 고유 고객아이디 혹은 유니크키
└custIpAN(15)영문+숫자, 최대 15byte
고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소

응답 파라미터

카드등록 완료 또는 실패 시 nextUrl로, 고객이 결제창 내 X 버튼을 클릭하면 cancUrl로 리다이렉트되며 아래 파라미터가 전달됩니다. 브라우저 종료 및 뒤로가기는 감지되지 않습니다.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*nxca_jt_gu
헥토파이낸셜에서 부여하는 고유 상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메세지 (URL Encoding, UTF-8)
└methodAN(20)영문+숫자, 최대 20byte*card
PG 서비스에 해당하는 결제 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5PaddingHongGilDong
상점에서 보내주는 고유 고객아이디 혹은 유니크키
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCAnxca_jt_il0211129135810M1494620
헥토파이낸셜 거래번호
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytename=HongGilDong&age=25
요청으로 받은 필드값을 응답으로 Bypass
└authDtN(14)숫자, 최대 14byte20211231100000
카드를 인증 받은 일시
└cardNoMaskingAN(20)영문+숫자, 최대 20byte532312******8756
마스킹된 카드번호
└cardKindAHN(50)영문+한글+숫자, 최대 50byte비씨 체크카드
카드 종류
└fnNmAH(20)영문+한글, 최대 20byte비씨(페이북)
신용카드 카드사명
└fnCdAN(4)영문+숫자, 최대 4byteBCC
신용카드 카드사 코드
└billKeyAN(50)영문+숫자, 최대 50byte*SBILL_0123456789
빌키 서비스 이용시 발급되는 자동결제키. 2회차 결제 시 사용
*영업 담당자를 통해 별도 신청 필요

노티 전문 (결과통보)

카드등록이 성공적으로 완료되면 헥토파이낸셜에서 가맹점으로 노티(결과통보)가 전송됩니다. 업무구분(bizType)은 A8(빌키발급)로 전달됩니다.

NOTE

노티 전문 확인

신용카드 결과통보 파라미터와 처리 방법은 노티 전문 문서를 참고하세요.
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?

무엇이든 물어보세요