헥토파이낸셜 개발자센터

신용카드 결제 API

결제창 없이 서버에서 직접 카드 정보를 전송하여 결제하는 API입니다. 빌키(자동결제키) 발급도 함께 가능합니다.

테스트용 키 정보

API 정보

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

결제 방식 안내

NOTE

결제 방식에 따른 필수 파라미터

구인증: 카드번호, 유효기간(yyMM), 식별번호, 카드비밀번호로 결제 요청 / 비인증: 카드번호, 유효기간(yyMM)으로 결제 요청
  • 빌키(자동결제 키) 발급: 상점 아이디 설정에 따라 빌키를 응답 값으로 내려드리고 있으며, 빌키를 따로 저장하였다가 결제가 필요할 경우 빌키 결제로 요청해 주세요.
  • 상점 아이디에 빌키 발급 설정은 영업 담당자를 통해 요청해 주세요.

요청 파라미터

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

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_ks_gu: 구인증 nxca_jt_bi: 비인증
└verAN(4)영문+숫자, 최대 4byte*
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*
결제수단
*고정값
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
*고정값
└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(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└pmtprdNmAHN(128)영문+한글+숫자, 최대 128byte*
결제상품명
└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byte*
상점 고객명
└mchtCustIdAHN(50)영문+한글+숫자, 최대 50byte*
상점 고객아이디
└emailAN(60)영문+숫자, 최대 60byte
상점 고객 이메일주소
└cardNoN(16)숫자, 최대 16byte*AES-256AES-256/ECB/PKCS5Padding + Base64
카드번호
└vldDtMonN(2)숫자, 최대 2byte*AES-256AES-256/ECB/PKCS5Padding + Base64
유효기간 (월) MM
└vldDtYearN(2)숫자, 최대 2byte*AES-256AES-256/ECB/PKCS5Padding + Base64
유효기간 (년) YY
└idntNoN(10)숫자, 최대 10byte*AES-256AES-256/ECB/PKCS5Padding + Base64
식별번호. 생년월일 6자리 또는 사업자번호 10자리
*구인증 결제시에만 사용
└cardPwdN(2)숫자, 최대 2byte*AES-256AES-256/ECB/PKCS5Padding + Base64
카드비밀번호 앞 2자리
*구인증 결제시에만 사용
└instmtMonN(2)숫자, 최대 2byte*
할부개월수 2자리
00: 일시불 02~12: 해당 개월수
└crcCdA(3)영문, 최대 3byte*
통화구분
KRW: 국내결제 USD: 해외결제
└taxTypeCdA(1)영문, 최대 1byte
세금유형. 공백일 경우 상점 설정에 따름
N: 과세 Y: 면세 G: 복합과세
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
*KRW: 1000 / USD: ex) $1.50 → 150
└taxAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
거래금액 중 과세금액 (복합과세일 경우 필수)
└vatAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
거래금액 중 부가세금액 (복합과세일 경우 필수)
└taxFreeAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
거래금액 중 비과세금액 (복합과세일 경우 필수)
└svcAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
신용카드 봉사료
└notiUrlAN(250)영문+숫자, 최대 250byte*
결제완료 후, 헥토파이낸셜에서 상점으로 전달하는 노티(결과통보)를 수신하는 Callback URL
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드

응답 파라미터

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

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*nxca_jt_bi
헥토파이낸셜에서 부여하는 고유 상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A19
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*CA
결제수단
*고정값
└bizTypeAN(2)영문+숫자, 최대 2byte*B0
업무 구분코드
*고정값
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점에서 생성하는 고유한 주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCAnxca_jt_il0211129135810M1494620
헥토파이낸셜에서 발급한 고유한 거래번호
└trdDtN(8)숫자, 최대 8byte*20211231
현재 전문을 전송하는 일자 (YYYYMMDD)
└trdTmN(6)숫자, 최대 6byte*100000
현재 전문을 전송하는 시간 (HHMMSS)
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과 메세지 (URL Encoding, UTF-8)

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*
요청시 hash 값 그대로 return
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*KRW: 1000 / USD: ex) $1.50 → 150
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└billKeyAN(50)영문+숫자, 최대 50byteSBILL_0123456789
2회차 결제시 사용되는 빌키
*빌키 서비스 이용 상점에 한하여 제공
└cardNoN(16)숫자, 최대 16byte111122xxxxxx4444
마스킹 된 카드번호
*기본적으로 제공되지 않으며, 특정 상점에 한하여 제공. 사업부에 문의
└vldDtMonN(2)숫자, 최대 2byte12
유효기간 (월) MM
*빌키 서비스 이용 상점에 한하여 제공
└vldDtYearN(2)숫자, 최대 2byte24
유효기간 (년) YY
*빌키 서비스 이용 상점에 한하여 제공
└issrIdAN(4)영문+숫자, 최대 4byte*NHC
카드발급사 코드 (신용카드 식별자 참고)
└cardNmAHN(20)영문+한글+숫자, 최대 20byte*NH 농협
카드사 명 (신용카드 식별자 참고)
└cardKindAHN(50)영문+한글+숫자, 최대 50byte*NH 체크카드
카드 종류 (신용카드 식별자 참고)
└ninstmtTypeCdA(1)영문, 최대 1byte*N
무이자할부타입
Y: 무이자(부분,상점) N: 일반할부, 일시불
└instmtMonN(2)숫자, 최대 2byte00
요청 시 값 그대로 return
└apprNoN(15)숫자, 최대 15byte*30001234
카드 승인번호

요청 예시

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "100000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c",
    "pmtprdNm": "테스트상품",
    "mchtCustNm": "홍길동",
    "mchtCustId": "HongGilDong",
    "email": "HongGilDong@example.com",
    "cardNo": "AES암호화된카드번호",
    "vldDtMon": "AES암호화된월",
    "vldDtYear": "AES암호화된년",
    "instmtMon": "00",
    "crcCd": "KRW",
    "taxTypeCd": "N",
    "trdAmt": "AES암호화된금액"
  }
}

응답 예시

성공 응답

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "STFP_PGCAnxca_jt_il0211129135810M1494620",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "정상적으로 처리되었습니다."
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c",
    "trdAmt": "AES암호화된금액",
    "billKey": "SBILL_0123456789",
    "issrId": "NHC",
    "cardNm": "NH 농협",
    "cardKind": "NH 체크카드",
    "ninstmtTypeCd": "N",
    "instmtMon": "00",
    "apprNo": "30001234"
  }
}

실패 응답

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0031",
    "outRsltCd": "1001",
    "outRsltMsg": "결제 요청 정보 누락"
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c"
  }
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?