신용카드 노티 전문
거래가 정상적으로 완료되면, 헥토파이낸셜에서 가맹점으로 노티(결과통보) 메세지가 전송됩니다. 자세한 설명은 결과통보 URL 가이드를 참고하세요.
NOTE
notiUrl이란?
notiUrl은 PG사 서버에서 가맹점 서버로 직접 결제 결과를 전송하는 Server-to-Server 방식의 웹훅입니다. 브라우저를 거치지 않아 안정적으로 결과를 수신할 수 있습니다.
NOTE
간편결제로 결제한 경우
신용카드 표준 결제창에서 고객이 간편결제(카카오페이·네이버페이 등)로 결제한 경우, 결과는 결제수단 코드 PZ의 간편결제 노티로 전송됩니다. 파라미터는 아래 간편결제 노티 문서를 참고하세요. 간편결제 노티 전문 보기
통신 규격
| 구분 | 내용 |
|---|---|
| 전송 방식 | POST |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| 응답 형식 | Plain Text (OK 또는 FAIL) |
취소 노티 안내
취소 노티는 기본 미제공
신용카드 결제 취소는 API 응답으로 결과를 확인하므로, 기본적으로 취소 노티가 전송되지 않습니다. 취소 노티가 필요한 경우 영업 담당자 또는 기술지원 이메일(pgsupport@hecto.co.kr)로 요청하세요.
노티 파라미터
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└outStatCdN(4)숫자, 최대 4byte*거래상태
0021거래상태
0021: 성공└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜에서 부여하는 고유 거래번호
STFP_PGCAnxca_jt_il0211129135810M1494620헥토파이낸셜에서 부여하는 고유 거래번호
└methodA(2)영문, 최대 2byte*결제수단
CA결제수단
CA: 신용카드└bizTypeAN(2)영문+숫자, 최대 2byte*업무구분
B0업무구분
B0: 승인 C0: 취소 A8: 빌키발급└mchtIdAN(12)영문+숫자, 최대 12byte*헥토파이낸셜에서 부여하는 상점아이디
nxca_jt_il헥토파이낸셜에서 부여하는 상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문 번호
ORDER20211231100000상점에서 생성하는 고유 주문 번호
└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byte실제 결제자의 주문자명
홍길동실제 결제자의 주문자명
└mchtNameAHN(20)영문+한글+숫자, 최대 20byte실 판매자명. 거래 요청시 실 판매자명이 없는 경우 헥토파이낸셜와 계약된 상점명
헥토파이낸셜실 판매자명. 거래 요청시 실 판매자명이 없는 경우 헥토파이낸셜와 계약된 상점명
└pmtprdNmAHN(128)영문+한글+숫자, 최대 128byte고객이 주문한 결제 상품명
테스트상품고객이 주문한 결제 상품명
└trdDtmN(14)숫자, 최대 14byte*거래일시. 승인일시, 취소/부분취소거래: 취소일시가 전달됩니다. 형식: YYYYMMDDhhmmss
20211231100000거래일시. 승인일시, 취소/부분취소거래: 취소일시가 전달됩니다. 형식: YYYYMMDDhhmmss
└trdAmtN(12)숫자, 최대 12byte거래금액
1000거래금액
└svcAmtN(12)숫자, 최대 12byte신용카드 봉사료. 오프라인거래이면서 봉사료 포함거래일 경우 전달
0신용카드 봉사료. 오프라인거래이면서 봉사료 포함거래일 경우 전달
└billKeyAN(40)영문+숫자, 최대 40byte자동결제 2회차를 위한 billKey발급
SBILL_0123456789자동결제 2회차를 위한 billKey발급
└billKeyExpireDtN(4)숫자, 최대 4byte자동결제키 유효기간 (YYMM)
2212자동결제키 유효기간 (YYMM)
*사전 협의된 가맹점에 한해 제공
└cardNmAHN(20)영문+한글+숫자, 최대 20byte카드사 명
NH 체크카드사 명
└emailAN(60)영문+숫자, 최대 60byte상점 고객 이메일
HongGilDong@example.com상점 고객 이메일
└mchtCustIdAN(50)영문+숫자, 최대 50byte상점 고객 아이디
HongGilDong상점 고객 아이디
└cardNoAN(20)영문+숫자, 최대 20byte마스킹된 카드번호 (상점 설정 정보에 따른 옵션값)
123456******7890마스킹된 카드번호 (상점 설정 정보에 따른 옵션값)
*앱카드·간편결제 카드는 실 카드번호와 상이할 수 있습니다.
└cardApprNoAN(15)영문+숫자, 최대 15byte카드 승인 번호
30001234카드 승인 번호
└instmtMonN(2)숫자, 최대 2byte할부 개월 수
00할부 개월 수
└instmtTypeA(1)영문, 최대 1byte할부 개월이 카드사 이벤트에 속하는 경우 Y (상점 설정 정보에 따른 옵션값)
N할부 개월이 카드사 이벤트에 속하는 경우 Y (상점 설정 정보에 따른 옵션값)
└orgTrdNoAN(40)영문+숫자, 최대 40byte취소 시, 원거래 번호
STFP_PGCAnxca_jt_il0211129135810M1494620취소 시, 원거래 번호
└orgTrdDtN(8)숫자, 최대 8byte취소 시, 원거래 일자
20211231취소 시, 원거래 일자
└mixTrdNoAN(40)영문+숫자, 최대 40byte복합결제 거래번호
STFP_PGCAnxca_jt_il0211129135810M1494620복합결제 거래번호
└mixTrdAmtN(12)숫자, 최대 12byte복합결제 금액. mixTrdNo가 존재하는 경우에만 전달
1000복합결제 금액. mixTrdNo가 존재하는 경우에만 전달
└payAmtN(12)숫자, 최대 12byte실 결제금액. 거래금액에서 복합결제 금액을 제외한 결제 금액 (payAmt = trdAmt - mixTrdAmt). mixTrdNo가 존재하는 경우에만 전달
1000실 결제금액. 거래금액에서 복합결제 금액을 제외한 결제 금액 (payAmt = trdAmt - mixTrdAmt). mixTrdNo가 존재하는 경우에만 전달
└cnclTypeN(2)숫자, 최대 2byte취소거래타입
00취소거래타입
00: 전체 취소 10: 부분 취소└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte상점에서 이용하는 추가 정보 필드로 전달한 값이 그대로 반환됩니다.
name=HongGilDong&age=25상점에서 이용하는 추가 정보 필드로 전달한 값이 그대로 반환됩니다.
└pktHashAN(64)영문+숫자, 최대 64byte*SHA256 해쉬값
a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1SHA256 해쉬값
NOTE
해쉬 생성 조합
outStatCd + 거래일자(trdDtm 앞 8자리) + 거래시간(trdDtm 뒤 6자리) + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└vatN(12)숫자, 최대 12byte부가세금액
91부가세금액
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
└taxAmtN(12)숫자, 최대 12byte과세금액
909과세금액
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
└taxFreeAmtN(12)숫자, 최대 12byte비과세금액
0비과세금액
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
└acqrCdAN(4)영문+숫자, 최대 4byte매입사 코드
NICE매입사 코드
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
└bizRegNoAN(10)영문+숫자, 최대 10byte가맹점 사업자번호
1234567890가맹점 사업자번호
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
└joinNoAN(30)영문+숫자, 최대 30byte가맹점번호
123456789가맹점번호
*오프라인 PG 이용 시, VAN사에 따라 전달 여부가 다름
노티 응답 (가맹점 → 헥토파이낸셜)
가맹점에서 헥토파이낸셜로 응답을 전송합니다.
| 응답 | 설명 |
|---|---|
OK | 성공 (대문자). 노티 수신 완료로 처리됩니다. |
FAIL | 명확한 실패로 인식합니다 (대문자). 노티가 재전송됩니다. |
| 그 외 | 비정상 실패로 인식하여 상점별 설정된 횟수만큼 재전송합니다. 재전송 기준일 초과 시 전송이 중단됩니다. |
응답 형식 주의
응답은 Plain Text로 'OK'만 보내야 합니다. 공백이나 다른 문자가 포함되면 실패로 간주되어 재전송이 발생할 수 있습니다.
해쉬 검증
해쉬 검증 필수
데이터 위변조를 체크하기 위해 notiUrl로 수신받은 해시데이터를 반드시 검증해야 합니다. 일치하는 경우에만 서비스를 제공하세요.
// Node.js 해시 검증 예시
const crypto = require('crypto');
function verifyHash(data, hashKey) {
const { outStatCd, trdDtm, mchtId, mchtTrdNo, trdAmt, pktHash } = data;
const trdDt = trdDtm.substring(0, 8); // YYYYMMDD
const trdTm = trdDtm.substring(8, 14); // HHmmss
const hashString = outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt + hashKey;
const calculatedHash = crypto.createHash('sha256').update(hashString, 'utf8').digest('hex');
return pktHash === calculatedHash;
}
노티 예시
승인 노티 (헥토파이낸셜 → 가맹점)
POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
outStatCd=0021
&trdNo=STFP_PGCAnxca_jt_il0211231100000M1234567
&method=CA
&bizType=B0
&mchtId=nxca_jt_il
&mchtTrdNo=ORDER20211231100000
&mchtCustNm=홍길동
&mchtName=헥토파이낸셜
&pmtprdNm=테스트상품
&trdDtm=20211231100000
&trdAmt=50000
&cardCd=HDC
&cardNm=현대카드
&cardNo=123456******7890
&cardApprNo=30001234
&instmtMon=00
&instmtType=N
&email=test@example.com
&mchtCustId=customer123
&mchtParam=
&pktHash=a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1
응답 (가맹점 → 헥토파이낸셜)
OK
