헥토파이낸셜 개발자센터

간편 정기결제 API

간편결제(카카오페이, 네이버페이)에서 발급받은 빌키를 사용하여 정기결제(자동결제)를 수행하는 API입니다.

테스트용 키 정보

API 정보

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

주의 사항

정기결제 빌키 발급 필수

정기결제 빌키를 발급받으려면 각 간편결제사의 정기결제 서비스가 설정된 상점아이디를 사용해야 합니다. 일반결제용 상점아이디로는 빌키가 발급되지 않습니다.
  • 카카오페이, 네이버페이를 지원합니다.
  • 발급된 빌키는 billKey 파라미터로 정기결제 API 호출 시 사용합니다.
  • 정기결제 호출 시 mUserId(고객 아이디)는 빌키 발급 시 사용한 값과 동일해야 합니다.
  • 빌키 발급 결제창: 카카오페이 결제창 / 네이버페이 결제창

빌키 발급 절차

  1. 각 간편결제 결제창 호출 시 정기결제 서비스가 설정된 상점아이디 사용
  2. autoPayType 파라미터 설정 (카카오페이: A 또는 S / 네이버페이: A)
  3. 결제 성공 시 응답에서 billKey 수신

요청 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nxkkp_auto: 카카오페이 정기결제 (자동결제)
└verAN(4)영문+숫자, 최대 4byte*
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*
결제수단
*고정값 (PZ: 간편결제)
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
*고정값 (B3: 정기결제)
└encCdN(2)숫자, 최대 2byte*
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유한 주문번호
└trdDtN(8)숫자, 최대 8byte*
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HH24MISS)
└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 + trdAmtEnc(평문) + hashKey
└corpPayCodeAN(40)영문+숫자, 최대 40byte*
간편결제사 ID
KKP: 카카오페이 NVP: 네이버페이
└mUserIdAHN(50)영문+한글+숫자, 최대 50byte*
빌키 발급 시 사용한 상점 고객 아이디
*빌키 발급 시 사용한 고객 아이디와 동일해야 합니다.
└ordNmAHN(30)영문+한글+숫자, 최대 30byte*
주문자명
└crcCdA(3)영문, 최대 3byte*
통화 구분 값
*고정값
└taxTypeA(1)영문, 최대 1byte
과세유형
N: 과세 Y: 면세 G: 복합과세
└trdAmtEncN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
└taxAmtEncN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
과세금액 (복합과세인 경우 필수)
└vatAmtEncN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
부가세금액 (복합과세인 경우 필수)
└taxFreeAmtEncN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
면세금액 (복합과세인 경우 필수)
└svcAmtEncN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
봉사료
└billKeyAN(50)영문+숫자, 최대 50byte*
헥토파이낸셜에서 발급한 빌키
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*
결제상품명
└etcOrdInfoAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드
└csrcIssReqYnA(1)영문, 최대 1byte
현금영수증 발행여부
Y: 발행 N: 미발행
*네이버페이 전용
└cashRcptPrposDivCdN(1)숫자, 최대 1byte
현금영수증 용도구분
0: 소득공제 1: 지출증빙
*현금영수증 사용 시 필수. 네이버페이 전용
└csrcRegNoDivCdN(1)숫자, 최대 1byte
등록번호 구분코드
1: 카드 2: 주민번호 3: 사업자번호 4: 휴대폰번호
*현금영수증 사용 시 필수. 네이버페이 전용
└csrcRegNoAN(64)영문+숫자, 최대 64byteAES-256AES-256/ECB/PKCS5Padding + Base64
고유식별정보
*현금영수증 사용 시 필수. 네이버페이 전용

응답 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*nxkkp_auto
상점아이디
└verAN(4)영문+숫자, 최대 4byte0A19
전문의 버전
└methodA(2)영문, 최대 2bytePZ
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byteB3
업무 구분코드
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGPZnx_mid_hd0230315153232M1196602
헥토파이낸셜 거래번호
└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...
요청시 hash 값 그대로 return
└AuthTrdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCAnxca_jt_il0211129135810M1494620
결제 시 헥토파이낸셜에서 발급한 거래번호
└TrdAmtEncN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└csrcIssNoAN(9)영문+숫자, 최대 9byte0123456789
현금영수증 승인번호
*네이버페이 전용

노티 전문

NOTE

노티 없음

간편 정기결제 API는 노티 전문이 없습니다. 응답 전문으로 결과를 확인해 주세요.
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?