FRONTEND CASE STUDY 문서 기반 시뮬레이션

결제 모듈 연동.

Next.js 결제 웹과 TypeScript SDK. iframe 메시지, 모바일 리다이렉트, PG 요청 변환과 서버 결과 polling이 연결되는 구조를 살펴봅니다.

WEB결제 화면

React · Next.js · TypeScript

SDK호스트 인터페이스

TypeScript · iframe · postMessage

PG결제 요청 변환

PortOne · 수단별 어댑터

DATA조회와 상태

TanStack Query · Zustand · RHF

구현 기록을 바탕으로 재구성한 공개용 사례입니다. 모듈과 호출 흐름을 설명하고, 코드·타입·식별자는 공개용 예제로 새로 작성했습니다.

01 / SYSTEM MAP

결제 웹이 연결하는 두 개의 경계

호스트와는 SDK로, 업무 API와는 HTTP로, PG와는 브라우저 SDK로 연결됩니다. 노드를 누르면 해당 모듈의 입출력과 실행 위치를 볼 수 있습니다.

RUNTIME / 실행 구조구현 기록 기반

SDK ↔ 웹iframe · 메시지 / 모바일 이동

웹 ↔ API조회 · 생성 · polling

웹 ↔ PGPG 호출 · 응답 / 복귀

Next.js / React

표시 Query → 폼 검증 → 결제 생성 mutation → PG 호출 → 결과 Query를 연결합니다. 업무 API와 PG SDK에 각각 요청하며, 최종 결과는 메시지 또는 호스트 복귀로 전달합니다.

BROWSER → API결제 API는 브라우저에서 직접 호출

표시 조회·결제 생성·결과 polling이 업무 API로 향합니다. 모든 요청이 Next 서버를 경유하는 구조는 아닙니다.

PG RETURN → RESULT QUERYPG 응답 뒤에 결과 조회가 한 번 더

PG가 돌려준 신호로 서버 결과 조회를 시작합니다. 최종 결과를 확인한 뒤 호스트에 통지합니다.

MODULE / INPUT → OUTPUT

01 / APP

라우트 식별자 → 서버 prefetch → HydrationBoundary → 폼 초기화

요청별 Provider와 브라우저 Query가 같은 조회 키를 연결합니다.