헥토파이낸셜 개발자센터

010 가상계좌

휴대폰 번호(010-XXXX-XXXX) 기반의 가상계좌 서비스입니다. 고객의 휴대폰 점유인증을 통해 010 형식의 입금전용 가상계좌 번호를 발급합니다.

지원 결제수단

결제 방식설명결제창 지원API 지원
결제창 채번결제창에서 휴대폰 점유인증 후 가상계좌 발급O-
API 채번API로 직접 휴대폰 인증 및 가상계좌 발급-O

010 가상계좌 개발 문서 바로가기

🪟

결제창 (UI)

결제창을 통한 가상계좌 발급

📱

휴대폰 인증 API

휴대폰 점유인증 요청/확인

🏦

채번 API

가상계좌 번호 발급

❌

채번취소

입금 전 가상계좌 취소

결제 이해하기

결제창(UI) 방식

결제창 방식에서는 휴대폰 점유인증(S1/S2)과 채번(A4)이 자동으로 처리됩니다.

구매자
가맹점
헥토파이낸셜
K뱅크
11. 결제창 호출
22. 휴대폰 점유인증 요청 (SMS)
33. 인증번호 입력
44. 010 가상계좌 채번 요청
55. 가상계좌 번호 발급
66. 채번 노티 전송 (notiUrl)
77. 채번 결과 표시 (nextUrl)
88. 고객 입금
99. 입금 확인
1010. 입금 노티 전송 (notiUrl)
NOTE

노티(notiUrl) 2회 전송

가상계좌 거래는 채번 노티(outStatCd: 0051)와 입금 노티(outStatCd: 0021) 총 2번의 노티가 전달됩니다. 반드시 두 노티를 모두 처리해야 합니다. DB 처리는 반드시 notiUrl에서 수행하고, nextUrl은 결과 화면 표시 용도로만 사용하세요.

API 방식 - B2C

결제창을 사용하지 않는 경우, 가맹점 서버에서 아래 순서대로 API를 직접 호출해야 합니다.

구매자
가맹점 서버
헥토파이낸셜
K뱅크
11. 결제 요청 (휴대폰번호 입력)
22. 휴대폰 점유인증 요청 (S1)
33. SMS 인증번호 발송
44. 인증번호 입력
55. 휴대폰 인증 확인 (S2)
66. 가상계좌 채번 요청 (A4)
77. K뱅크 가상계좌 발급
88. 발급 결과
99. 채번 노티 전송 (notiUrl)
1010. 고객 입금
1111. 입금 확인
1212. 입금 노티 전송 (notiUrl)

B2C API 호출 순서

순서APIbizType설명
1휴대폰 점유 인증 요청S1고객 휴대폰으로 SMS 인증번호 발송
2휴대폰 인증 확인S2고객이 입력한 인증번호 검증
3가상계좌 채번A4010 형식 가상계좌 번호 발급
NOTE

mchtTrdNo 동일 필수

S1(인증 요청)과 A4(채번)에서 사용하는 mchtTrdNo(상점주문번호)는 반드시 동일해야 합니다.

API 방식 - B2B

B2B 이용 시에는 채번 전에 동일 금액 확인(A7) API를 추가로 호출하여 중복 채번을 방지해야 합니다.

구매자
가맹점 서버
헥토파이낸셜
K뱅크
11. 결제 요청 (휴대폰번호 입력)
22. 휴대폰 점유인증 요청 (S1)
33. SMS 인증번호 발송
44. 인증번호 입력
55. 휴대폰 인증 확인 (S2)
66. 동일 금액 확인 (A7)
77. 가상계좌 채번 요청 (A4)
88. K뱅크 가상계좌 발급
99. 발급 결과
1010. 채번 노티 전송 (notiUrl)
1111. 고객 입금
1212. 입금 확인
1313. 입금 노티 전송 (notiUrl)

B2B API 호출 순서

순서APIbizType설명
1휴대폰 점유 인증 요청S1고객 휴대폰으로 SMS 인증번호 발송
2휴대폰 인증 확인S2고객이 입력한 인증번호 검증
3동일 금액 확인A7동일 금액으로 이미 채번된 거래 확인 (B2B 필수)
4가상계좌 채번A4010 형식 가상계좌 번호 발급

B2B 동일 금액 확인 필수

B2B 서비스 이용 시 A7(동일 금액 확인) 없이 A4(채번)를 요청하면, 이미 발급된 동일 금액의 가상계좌가 있을 경우 VA03 에러로 채번이 실패합니다.

B2C와 B2B 차이점

구분B2CB2B
입금 만료최대 27일최대 3년
통장인자명"010가상계좌" 고정"010_고객명" 형식
가상계좌번호휴대폰번호휴대폰번호 + 3자리
거래금액실제 결제 금액1원 이상 (실제 입금액과 무관)
동일 금액 확인 (A7)불필요필수

입금 후 처리

가상계좌 정상 발급 후 고객이 해당 계좌에 입금하면, 헥토파이낸셜에서 가맹점으로 **입금 결과 노티(notiUrl)**를 전송합니다.

  • 채번 취소 (A2): 고객 입금 전에 발급된 가상계좌를 취소합니다.
  • 환불 (C0): 고객 입금 후에 환불 처리합니다. (별도 환불 서비스 등록 필요)

주요 기능 및 특징

특징설명
휴대폰 기반010 형식의 휴대폰 번호가 가상계좌 번호로 사용됩니다
점유인증 필수휴대폰 점유인증을 통해 본인 확인 후 계좌 발급
K뱅크 연동K뱅크(089)를 통한 가상계좌 서비스
입금 만료 설정B2C: 최대 27일, B2B: 최대 3년

이런 서비스에 적합합니다

  • 본인 확인 필수 결제: 휴대폰 점유인증으로 본인 확인이 필요한 서비스
  • 간편한 입금: 고객이 기억하기 쉬운 010 번호 형식의 계좌
  • B2B 거래: 긴 입금 기한(최대 3년)이 필요한 기업간 거래

주의사항

운영 환경 테스트 주의

운영환경에서 테스트 시 발생하는 비용은 가맹점에서 부담합니다. 반드시 테스트베드에서 모든 테스트를 완료 후 운영환경을 이용해야 합니다.

점유인증 생략 조건

결제창(UI) 방식에서는 점유인증 생략 불가

결제창은 항상 UI 내에서 점유인증(SMS 발송 → 인증번호 입력)을 진행합니다. 아래 생략 조건은 API 방식에서만 유효합니다.

다음 조건을 모두 만족하는 경우 S1(인증 요청) → S2(인증 확인) 단계를 생략하고 A4(채번)를 바로 요청할 수 있습니다.

  • cphoneNo(휴대폰번호)와 mchtCustId(상점고객아이디)를 A4 채번 요청 시 함께 전송
  • 동일한 cphoneNo + mchtCustId 조합으로 27일 이내 점유인증(S1/S2) 완료 이력이 있어야 함

두 조건 중 하나라도 충족되지 않으면 S1 → S2 → A4 순서로 진행해야 합니다.

입금 만료일 설정

  • 입금만료일(expireDt)을 넣지 않으면 거래일 기준 +10일로 자동 설정됩니다.
  • B2C: 현재일자 기준 최대 27일
  • B2B: 현재일자 기준 최대 3년

통장인자명

  • B2C: "010가상계좌" 고정
  • B2B: "010_고객명" 형식

연동 정보

결제창(UI) URI

구분URL
테스트베드https://tbnpg.settlebank.co.kr
상용 환경https://npg.settlebank.co.kr

API URI

구분URL
테스트베드https://tbgw.settlebank.co.kr
상용 환경https://gw.settlebank.co.kr

보안 정보

암호화 방식 (AES-256)

개인정보가 포함된 파라미터는 암호화하여 전송해야 합니다.

구분항목
알고리즘AES-256/ECB/PKCS5Padding
인코딩Base64 Encoding
대상 필드거래금액, 고객명, 휴대폰번호, 이메일 등

위변조 방지 (SHA-256)

요청 데이터의 위변조를 방지하기 위해 해시값을 생성합니다.

구분항목
알고리즘SHA-256
인코딩Hex Encoding

테스트용 키 정보

테스트 전용 정보

위 키와 상점 ID는 테스트 환경에서만 사용하세요. 운영 환경에서는 헥토파이낸셜에서 별도 발급하는 키와 상점 ID를 사용해야 합니다.

API 전체 목록

구분API설명bizType
결제창 연동채번 (단독창)UI 결제창을 통한 가상계좌 발급-
결제창 연동채번 (통합결제창)통합결제창을 통한 가상계좌 발급-
API 연동휴대폰 점유 인증SMS 인증번호 발송 요청S1
API 연동휴대폰 인증 확인SMS 인증번호 확인S2
API 연동동일 금액 확인동일 금액 중복 채번 확인 (B2B 필수)A7
API 연동채번가상계좌 번호 발급A4
API 연동채번 취소발급된 가상계좌 취소 (입금 전)A2
API 연동환불입금 완료 건 환불 처리C0
노티입금통보고객 입금 시 결과 통보B1
테스트입금테스트테스트 환경 입금 시뮬레이션F1

더 많은 API 문서

🔍

동일 금액 확인

B2B 중복 채번 방지 (A7)

↩️

환불

입금 완료 건 환불 처리

🔔

입금통보 노티

입금 완료 시 노티 처리

🧪

입금테스트

테스트 환경 입금 시뮬레이션

❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?