헥토파이낸셜 개발자센터

휴대폰 승인 API (하이브리드)

하이브리드 방식은 결제창에서 인증만 진행하고, 승인은 가맹점 서버에서 별도로 요청하는 방식입니다. 인증과 승인을 분리하여 처리할 수 있습니다.

테스트용 키 정보

API 정보

POST/spay/APIService.do
Content-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APIService.do
운영https://gw.settlebank.co.kr/spay/APIService.do

주의 사항

NOTE

하이브리드 결제 흐름

1) 결제창에서 인증 요청 (linkMethod='HBRD') → 2) 인증 성공 응답 (outStatCd='0061') → 3) 이 API로 승인 요청
  • 결제창 요청 시 linkMethod 파라미터를 HBRD로 설정해야 합니다.
  • 인증 성공 시 outStatCd가 0061로 응답됩니다.
  • 인증 성공 후 응답받은 trdNo를 authTrdNo로 사용하여 승인 요청합니다.
  • 상점주문번호(mchtTrdNo)는 인증 요청 시 사용한 값과 동일해야 합니다.

요청 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nxhp_sb_hd: 하이브리드 테스트
└verAN(4)영문+숫자, 최대 4byte*
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*
결제수단
*고정값 (MP: 휴대폰결제)
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
B0: 페이레터 재판매 승인 B2: 헥토파이낸셜 원천 승인
*B0: 페이레터 재판매 승인, B2: 헥토파이낸셜 원천 승인
└encCdN(2)숫자, 최대 2byte*
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유한 주문번호 (인증 요청 시 사용한 값과 동일)
└trdDtN(8)숫자, 최대 8byte*
요청일자 (YYYYMMDD)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HHMMSS)
└mobileYnA(1)영문, 최대 1byte
모바일 여부
Y: 모바일웹/앱 N: PC 또는 그 외
└osTypeA(1)영문, 최대 1byte
OS 구분
A: Android I: iOS W: Windows M: Mac E: 기타

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└phoneNoN(11)숫자, 최대 11byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객 휴대폰 번호
└telCoA(3)영문, 최대 3byteAES-256AES-256/ECB/PKCS5Padding + Base64
통신사
SKT: SK Telecom KTF: KT LGT: LG U+ CJH: CJ헬로모바일 KCT: 한국케이블텔레콤 SKL: SK 7Mobile
└emailAN(60)영문+숫자, 최대 60byte
고객 이메일 주소
└mUserIdAHN(50)영문+한글+숫자, 최대 50byte
상점 고객아이디
└crcCdA(3)영문, 최대 3byte*
통화구분
*고정값
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*
상품명
└sellerNmAHN(128)영문+한글+숫자, 최대 128byte
판매자명
└ordNmAHN(30)영문+한글+숫자, 최대 30byte
주문자명
└getBillKeyYnA(1)영문, 최대 1byte
빌키발급여부
Y: 빌키발급 그외: 빌키미발급
└authTrdNoAN(40)영문+숫자, 최대 40byte*
인증 성공 시 헥토파이낸셜에서 응답한 거래번호
└linkMethodAN(12)영문+숫자, 최대 12byte*
연동 방식 코드
*고정값
└notiUrlAN(250)영문+숫자, 최대 250byte*
결제 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
상점 예약 필드

응답 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*nxhp_sb_hd
상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A19
전문의 버전
└methodA(2)영문, 최대 2byte*MP
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byte*B0
업무 구분코드
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGMPnxhp_sb_hd0211129135810M1494620
헥토파이낸셜 거래번호
└trdDtN(8)숫자, 최대 8byte*20211231
요청일자 (YYYYMMDD)
└trdTmN(6)숫자, 최대 6byte*100000
요청시간 (HHMMSS)
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
결과코드
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메시지

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*f395b6725a9a18...
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└phoneNoN(11)숫자, 최대 11byteAES-256AES-256/ECB/PKCS5Padding01012341234
고객의 휴대폰번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└telCoA(3)영문, 최대 3byteAES-256AES-256/ECB/PKCS5PaddingSKT
통신사
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└getBillKeyYnA(1)영문, 최대 1byte
빌키발급여부
Y: 빌키발급 그외: 빌키미발급
└billKeyAN(50)영문+숫자, 최대 50byteMO0123456789
헥토파이낸셜에서 발급하는 빌키 (2회차부터 사용)
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?

무엇이든 물어보세요