노티(notiUrl) 연동
결제가 완료되면 헥토파이낸셜 서버에서 가맹점 서버로 결과를 직접 전송합니다. 이를 노티(Notification) 또는 결과통보라고 합니다.
노티 연동 필수
nextUrl은 브라우저를 통해 전달되므로 네트워크 오류로 누락될 수 있습니다. 실제 주문 처리(재고 차감, DB 업데이트 등)는 반드시 노티(notiUrl)에서 수행해야 합니다.
노티란?
결제 결과를 전달받는 두 가지 방식이 있습니다.
고객
가맹점
헥토파이낸셜
1결제 요청
결제 요청
2결제창 호출
결제창 호출
3결제 진행
결제 진행
4노티 전송 (notiUrl)
노티 전송 (notiUrl)
5결과 페이지 (nextUrl)
결과 페이지 (nextUrl)
6리다이렉트
리다이렉트
| 전달 방식 | 설명 | 신뢰성 |
|---|---|---|
nextUrl | 브라우저 리다이렉트 | 낮음 (네트워크 오류 가능) |
notiUrl | 서버 간 직접 통신 (S2S) | 높음 (재전송 지원) |
NOTE
notiUrl vs nextUrl
notiUrl은 헥토파이낸셜 서버에서 가맹점 서버로 직접 전송되므로, 고객의 네트워크 상태와 무관하게 안정적으로 결과를 수신할 수 있습니다.
통신 규격
모든 결제수단에서 동일한 규격을 사용합니다.
| 구분 | 내용 |
|---|---|
| 전송 방식 | POST |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| 응답 형식 | Plain Text (OK 또는 FAIL) |
NOTE
캐릭터셋 변경 가능
캐릭터셋은 UTF-8 또는 EUC-KR로 제공됩니다. 변경이 필요한 경우 기술지원 이메일(pgsupport@hecto.co.kr)로 문의해 주세요.
응답 처리
| 응답 | 설명 |
|---|---|
OK | 성공. 노티 수신 완료로 처리됩니다. |
FAIL 또는 그 외 | 실패. 설정된 횟수까지 재전송됩니다. |
응답 형식 주의
응답은 Plain Text로 'OK'만 보내야 합니다. 공백, 줄바꿈, HTML 태그 등이 포함되면 실패로 간주됩니다.
해시 검증
데이터 위변조 방지를 위해 해시 검증은 필수입니다.
해시 생성 규칙
노티 해시 검증pktHash
| 필드명 | 파라미터 |
|---|---|
| 거래상태 코드 | outStatCd |
| 거래 일자 (trdDtm 앞 8자리) | trdDt |
| 거래 시간 (trdDtm 뒤 6자리) | trdTm |
| 상점 아이디 | mchtId |
| 상점 주문번호 | mchtTrdNo |
| 거래금액 | trdAmt |
| 라이센스키 | licenseKey |
SHA256(outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + licenseKey)NOTE
trdDt / trdTm 추출
노티 전문에는 trdDtm(14자리)이 전달됩니다. 해시 생성 시 trdDt(앞 8자리)와 trdTm(뒤 6자리)를 추출하여 사용합니다.
검증 예시 (Node.js)
const crypto = require('crypto');
function verifyNoti(data, licenseKey) {
const { outStatCd, trdDtm, mchtId, mchtTrdNo, trdAmt, pktHash } = data;
// trdDtm에서 일자/시간 분리
const trdDt = trdDtm.substring(0, 8); // YYYYMMDD
const trdTm = trdDtm.substring(8, 14); // HHmmss
// 해시 생성
const hashString = outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + licenseKey;
const calculatedHash = crypto.createHash('sha256').update(hashString, 'utf8').digest('hex');
return pktHash === calculatedHash;
}
// 사용 예시
app.post('/noti/hecto', (req, res) => {
if (!verifyNoti(req.body, HECTO_LICENSE_KEY)) {
console.error('해시 검증 실패');
return res.send('FAIL');
}
// 결제 처리 로직...
res.send('OK');
});
notiUrl 요구사항
- HTTPS 필수 (HTTP 불가)
- 외부 접근 가능한 URL
- 방화벽에서 헥토파이낸셜 IP 허용
자주 묻는 질문
노티가 수신되지 않아요
- notiUrl이 외부에서 접근 가능한지 확인
- HTTPS 인증서가 유효한지 확인
- 방화벽 설정 확인
- 응답으로
OK를 Plain Text로 반환하는지 확인
노티가 여러 번 와요
응답으로 OK를 반환하지 않으면 재전송됩니다. 응답 형식을 확인하세요.
취소 노티는 언제 오나요?
취소 노티는 기본적으로 발송되지 않습니다.
취소 API 호출 시 응답으로 결과를 바로 받기 때문에 별도의 노티가 필요하지 않습니다.
단, 가맹점 관리자에서 직접 취소하는 경우에는 가맹점 서버에서 결제 상태를 알 수 없으므로, 취소 노티를 발송하도록 설정할 수 있습니다. 취소 노티 수신이 필요하면 영업 담당자에게 설정을 요청해 주세요.
취소 노티 설정 시, 기본적으로 원 거래의 notiUrl로 발송됩니다. 원 거래에서 notiUrl을 설정하지 않았다면 취소 노티용 URL도 함께 전달해 주세요.
