결과통보 URL, 왜 필수일까? | 헥토파이낸셜 개발자센터

"결제는 성공했는데 주문 내역이 없어요?"

"고객이 결제 완료 문자까지 받았는데, 주문 내역이 없대요!"

결제 연동을 하다 보면 종종 마주치는 상황인데요. PG사 관리자 페이지를 확인하면 결제는 정상 승인되어 있지만, 주문 DB에만 내역이 없어요. 대부분 결제 완료 후 고객이 쇼핑몰로 돌아오는 과정에서 네트워크가 끊기거나 브라우저를 종료했을 때 발생해요.

브라우저를 통해 결제 결과를 전달받는 방식은 고객 환경에 의존하기 때문에 100% 신뢰할 수 없어요. 이 문제를 근본적으로 해결하는 것이 결과통보 URL(notiUrl) 이에요. 고객의 브라우저를 거치지 않고, PG사 서버가 가맹점 서버로 직접 결제 결과를 전송하죠.

이번 아티클에서는 notiUrl의 역할과 구현 방법을 알아볼게요.

결과통보 URL이란?

결과통보 URL(notiUrl)은 Server-to-Server 방식으로 결제 결과를 전달하는 웹훅(Webhook)이에요.

일반적인 결제 흐름의 한계

단계	흐름
1	고객 → PG 결제창에서 결제
2	PG사 → 결제 처리 완료
3	PG사 → 고객 브라우저를 nextUrl로 리다이렉트
4	브라우저 → 가맹점 서버로 결과 전달

문제: 3~4번에서 네트워크가 끊기면? 결제는 성공했지만 가맹점은 결과를 모르게 돼요.

결과통보 URL의 역할

결제 결과 전달에는 두 가지 경로가 있어요.

리다이렉트 방식 (불안정)

고객 브라우저

PG사

가맹점 서버

1① 결제창에서 결제

① 결제창에서 결제

2② 결제 완료 후 nextUrl로 리다이렉트

② 결제 완료 후 nextUrl로 리다이렉트

3③ 결과 전달 (네트워크 끊김 위험!)

③ 결과 전달 (네트워크 끊김 위험!)

notiUrl 방식 (안전)

고객 브라우저

PG사

가맹점 서버

1① 결제창에서 결제

① 결제창에서 결제

2② notiUrl로 직접 전송 (서버 간 통신)

② notiUrl로 직접 전송 (서버 간 통신)

3③ OK 응답

③ OK 응답

4④ nextUrl로 화면만 표시

④ nextUrl로 화면만 표시

리다이렉트 (불안정): nextUrl 을 통해 브라우저를 거쳐 전달되는 경로예요. 네트워크 환경에 따라 끊길 위험이 있어요.
notiUrl (안전): PG사 서버에서 가맹점 서버로 직접 연결되는 경로예요. 브라우저 상태와 무관하게 안전하게 결과를 전달해요.

PG사는 결제 처리가 완료되는 즉시 이 안전한 경로(notiUrl) 를 통해 결과를 전송하므로, 데이터 누락 걱정 없이 주문을 처리할 수 있어요.

nextUrl과 notiUrl의 차이

구분	nextUrl/cancUrl	notiUrl
통신 방식	브라우저 리다이렉트	Server-to-Server
신뢰도	낮음 (네트워크 오류 가능)	높음 (재시도 지원)
용도	고객에게 결과 화면 표시	서버에서 주문 처리
필수 여부	필수	필수
보안 검증	클라이언트 노출 가능	서버 간 통신

NOTE

실무 팁

nextUrl은 고객에게 결제가 완료되었습니다 라는 화면을 보여주는 용도로만 사용하세요. 실제 재고 차감이나 주문 상태 변경과 같은 핵심 로직은 반드시 notiUrl에서 처리해야 데이터 누락을 방지할 수 있습니다.

notiUrl 구현 시 핵심 포인트

notiUrl 은 PG사의 POST 요청을 처리하는 API예요. 핵심은 해시 검증 과 정확한 응답 이에요.

구현 시 확인사항

항목	설명
해시 검증	`pktHash` 값을 검증하여 요청 위변조 확인
중복 처리 방지	동일 주문이 여러 번 처리되지 않도록 방어 로직 필요
응답 형식	Plain Text로 `OK` 또는 `FAIL`만 응답
상태 분기	`outStatCd`가 `0021`이면 성공, `0031`이면 실패