헥토파이낸셜 개발자센터

신용카드 결제 (표준 결제창)

헥토파이낸셜 표준 결제창을 통해 신용카드 결제를 진행합니다.

테스트용 키 정보

API 정보

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

주의 사항

상점아이디 속성에 따른 화면 분기

상점아이디가 일반 인증 결제로 설정되어 있는 경우 카드사 인증창이 나타나고, 비인증 또는 구인증으로 설정되어 있는 경우 카드정보 입력창이 나타납니다.
NOTE

인증/승인 분리 방식

일반적으로 결제창에서 인증과 승인이 한 번에 처리됩니다 (outStatCd: 0021). 인증/승인 분리 상점아이디(nxca_jt_hd)를 사용하는 경우, 인증 성공 시 outStatCd: 0061이 반환되며 인증 단계에서 받은 거래번호(trdNo)를 이용해 별도로 승인 API를 호출해야 합니다. 신용카드 승인 API (인증/승인 분리) 참고
  • 신용카드 빌키(billKey)를 내려받고자 하는 경우, 빌키 서비스를 영업 담당자를 통해 별도 신청해야 합니다.
  • 빌키를 발급받은 경우, 해당 빌키로 2회차 결제 API 요청하면 됩니다. (신용카드 빌키 결제 API 참고)
  • 매출전표의 발행금액은 가맹점에서 전송하는 파라미터를 기준으로 표기됩니다.
    • 예) 과세 가맹점에서 거래금액 1,000원을 전송하는 경우
      • 거래금액만 전송: 과세 909, 부가세 91로 표기
      • 과세금액 900, 부가세금액 100 전송: 과세 900, 부가세 100으로 표기

요청 파라미터

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

필수 파라미터

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_jt_il: 인증 nxca_jt_bi: 비인증 nxca_ks_gu: 구인증 nxca_jt_hd: 인증 승인 분리
└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
거래금액 (USD 사용시 100을 곱하여 전달)
*KRW: 1000 / USD: ex) $1.00 → 100
└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
기타 주문 정보를 입력하는 상점 예약 필드
└emailAN(60)영문+숫자, 최대 60byteAES-256AES-256/ECB/PKCS5Padding + Base64
이메일 주소
└prdtTermN(14)숫자, 최대 14byte
상품제공기간 (yyyyMMddHHmmss). 값이 없으면 일반결제로 표기
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
상점에서 보내주는 고유 고객아이디 혹은 유니크키
└taxTypeCdA(1)영문, 최대 1byte
면세여부. 공백일 경우 상점 설정에 따름
N: 과세 Y: 면세 G: 복합과세
└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
신용카드 봉사료
└instmtMonN(2)숫자, 최대 2byte
할부개월수
00: 일시불 2~12: 할부개월수
*신용카드(일반): 요청된 할부 개월 수가 할부 개월 리스트에 있을 경우 선택된 상태로 고정, 요청된 할부 개월 수가 할부 개월 리스트에 없을 경우 선택 할 수 있도록 할부 개월 수 리스트 노출. 신용카드-직호출: 요청된 할부 개월 수로 결제
└cardTypeN(1)숫자, 최대 1byte
카드결제타입
3: 앱카드 전용가능 카드사[신한/삼성/현대/KB/농협/롯데] 6: 현대카드 PayShot(카드사와 직접 제휴계약 진행 후 사용가능)
└chainUserIdAN(100)영문+숫자, 최대 100byte
현대카드 PayShot ID. 카드사와 직접 제휴계약 진행 후 사용 가능
└cardGbAN(4)영문+숫자, 최대 4byte
특정카드사 코드. 하나의 특정 카드사만 노출
*카드사 코드는 카드사 코드 참조 페이지를 확인하세요.
└appSchemeAN(100)영문+숫자, 최대 100byte
앱스키마 (AppScheme://~) 형식. 자체앱을 구축하는 경우 사용
└custIpAN(15)영문+숫자, 최대 15byte
고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소

응답 파라미터

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

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*nxca_jt_il
헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_jt_il: 인증 nxca_jt_bi: 비인증 nxca_ks_gu: 구인증
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 성공 0061: 인증 성공(인증, 승인 분리 방식) 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
헥토파이낸셜 거래번호
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytename=HongGilDong&age=25
요청으로 받은 필드값을 응답으로 Bypass
└authDtN(14)숫자, 최대 14byte20211231100000
결제 승인 일시
└authNoN(15)숫자, 최대 15byte30001234
신용카드 승인 번호
└intMonN(2)숫자, 최대 2byte00
신용카드 할부 개월 수
└fnNmAH(20)영문+한글, 최대 20byte우리카드
신용카드 카드사명
└fnCdAN(4)영문+숫자, 최대 4byteLTC
신용카드 카드사 코드
└pointTrdNoAN(40)영문+숫자, 최대 40byteSTFP_PGCAnxca_jt_il0211129135810M1494620
고객이 포인트 결제를 했을 경우 포인트 결제 건 거래번호
└pointTrdAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding1000
고객이 포인트 결제를 했을 경우 포인트 결제 금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└cardTrdAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding4000
고객이 할인 받은 금액 또는 포인트금액을 제외한 신용카드 결제금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└billKeyAN(50)영문+숫자, 최대 50byte*SBILL_0123456789
빌키 서비스 이용시 발급되는 자동결제키. 2회차 결제 시 사용
*영업 담당자를 통해 별도 신청 필요

노티 전문 (결과통보)

결제 완료 후 헥토파이낸셜에서 가맹점으로 노티(결과통보)가 전송됩니다.

NOTE

노티 전문 확인

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

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?