@sayren/mcp 0.1.11 → 0.2.0

package/dist/index.mjs

@@ -510,24 +510,29 @@ const RULES = [
 		why: "클라이언트에서 다시 받으면 첫 화면이 비고 검색 노출이 죽는다. SSR을 끄지 않는다"
 	},
 	{
-		id: "popup-sync-open",
-		title: "결제 팝업은 클릭 콜스택에서 동기적으로 연다",
-		why: "API 응답을 기다린 뒤 열면 브라우저가 팝업을 막는다. 빈 창을 먼저 열고 주소를 넣는다"
+		id: "payment-browser-launch",
+		title: "결제창은 브라우저에서 `@sayren/storefront-sdk/payments`로 연다(`start` 또는 `open`)",
+		why: "결제창은 결제 서비스 주소를 브라우저 창으로 여는 일이다. 서버 파일에서 부르면 아무것도 열리지 않고 결제가 시작되지 않는다. 결제 시작(`startPayment`)은 서버 함수, 결제창은 브라우저다"
 	},
 	{
-		id: "popup-client-submit",
-		title: "주문서 제출은 클라이언트 제출(`onSubmit` + 서버 함수)로 한다",
-		why: "네이티브 폼은 문서를 다시 그려 팝업 제어 상태가 사라진다. 결제창이 빈 창으로 남는다"
+		id: "payment-popup-prepare",
+		title: "결제 시작이 서버 함수를 거치면 클릭 시점에 `payments.prepareWindow()`로 창을 먼저 연다",
+		why: "팝업은 사용자 클릭에서 동기로 열어야 차단되지 않는다. 서버 응답을 기다린 뒤 열면 브라우저가 막아 결제가 시작되지 않는다"
 	},
 	{
-		id: "parent-origin",
-		title: "결제 요청에 우리 화면의 origin을 실어 보낸다",
-		why: "결제 팝업은 그 값으로만 부모 창에 결과를 알린다. 빠지면 결제는 되는데 주문서가 완료를 못 받는다"
+		id: "payment-return-route",
+		title: "결제 복귀 화면에서 `payments.result()`로 결과를 읽는다",
+		why: "모바일·팝업 차단은 리다이렉트 결제다. 결제 서비스가 복귀 주소로 돌려보내므로 복귀 화면이 결제 상태를 확인하지 않으면 결제한 구매자가 결과를 볼 수 없다"
 	},
 	{
-		id: "popup-origin-check",
-		title: "팝업 메시지는 origin과 source를 모두 검증한다",
-		why: "검증 없이 받으면 아무 창이나 결제 완료를 흉내 낼 수 있다"
+		id: "payment-processing-status",
+		title: "결과 확인 중(`PROCESSING`)이면 결제 상태를 다시 조회한다",
+		why: "결과를 아직 모를 때 실패로 안내하면 구매자가 다시 결제해 이중 결제가 난다. 확정될 때까지 `payments.result()`·`payments.getStatus()`로 확인한다"
+	},
+	{
+		id: "checkout-origin",
+		title: "복귀 주소는 배포된 주소(요청 origin)에서 만들고 그 도메인을 셀러 콘솔 설정 › 결제에 등록한다",
+		why: "결제 도메인 밖의 복귀 주소는 서버가 거절한다. 주소를 코드에 고정하면 로컬·스테이징·운영 중 한 곳에서만 결제가 된다"
 	},
 	{
 		id: "analytics-start",
@@ -538,11 +543,6 @@ const RULES = [
 		id: "analytics-ids",
 		title: "서버의 API 클라이언트에 방문 식별 쿠키를 싣는다(`analyticsIdsFromCookie`)",
 		why: "빠지면 장바구니·결제 시작·구매가 방문과 이어지지 않아 퍼널과 유입별 매출에서 빠진다"
-	},
-	{
-		id: "closed-not-failed",
-		title: "팝업이 결과 없이 닫히면 실패로 단정하지 않는다",
-		why: "이미 승인됐을 수 있다. 서버에 결제 상태를 물어봐야 이중 결제와 누락 주문을 막는다"
 	}
 ];
 /** 주석을 걷어낸다 — 규칙을 설명하는 주석이 위반으로 잡히지 않게 한다 */
@@ -551,8 +551,6 @@ function stripComments(source) {
 }
 const CLIENT_FILE = /\.(ts|tsx)$/;
 const SERVER_FILE = /\.server\.(ts|tsx)$/;
-/** 문서를 다시 부르는 폼 — method나 action을 단 <form> */
-const NATIVE_SUBMIT_FORM = /<form\s[^>]*\b(method|action)=/;
 /**
 * 만들어진 프로젝트의 소스를 규칙과 대조한다. 정적 검사라 모든 문제를 잡지는 못하지만,
 * 여기 있는 것들은 실제로 반복해서 깨지는 것들이다.
@@ -564,6 +562,7 @@ function verifySources(files) {
 		content: stripComments(file.content)
 	}));
 	const has = (needle) => cleaned.some((file) => file.content.includes(needle));
+	const matches = (pattern) => cleaned.find((file) => pattern.test(file.content));
 	for (const file of cleaned) {
 		if (!CLIENT_FILE.test(file.path)) continue;
 		const isServer = SERVER_FILE.test(file.path) || /\/(server|\.server)\//.test(file.path);
@@ -582,23 +581,11 @@ function verifySources(files) {
 			file: file.path,
 			detail: "토큰처럼 보이는 값을 모듈 전역에 두었다"
 		});
-		if (/window\.open\(/.test(file.content) && /await .*\n?.*window\.open\(/.test(file.content)) findings.push({
-			ruleId: "popup-sync-open",
+		if (isServer && /@sayren\/storefront-sdk\/payments/.test(file.content)) findings.push({
+			ruleId: "payment-browser-launch",
 			file: file.path,
-			detail: "await 뒤에 팝업을 연다. 브라우저가 막는다"
+			detail: "서버 파일에서 결제 모듈을 쓴다. 결제창(`start`·`open`)과 복귀 처리(`result`)는 브라우저(컴포넌트·effect)에서 부른다"
 		});
-		if (/addEventListener\("message"/.test(file.content)) {
-			if (!/event\.origin|\.origin\s*!==/.test(file.content)) findings.push({
-				ruleId: "popup-origin-check",
-				file: file.path,
-				detail: "message 리스너가 origin을 검증하지 않는다"
-			});
-			if (!/event\.source|\.source\s*!==/.test(file.content)) findings.push({
-				ruleId: "popup-origin-check",
-				file: file.path,
-				detail: "message 리스너가 source(우리가 연 창)를 검증하지 않는다"
-			});
-		}
 		if (isServer && /createAnalytics\(/.test(file.content)) findings.push({
 			ruleId: "analytics-start",
 			file: file.path,
@@ -609,21 +596,33 @@ function verifySources(files) {
 			file: file.path,
 			detail: "서버 API 클라이언트에 방문 식별자가 없다. `...analyticsIdsFromCookie(request.headers.get(\"cookie\"))`를 넘긴다"
 		});
-		if (/requestPayment\(/.test(file.content) && NATIVE_SUBMIT_FORM.test(file.content)) findings.push({
-			ruleId: "popup-client-submit",
-			file: file.path,
-			detail: "결제 화면이 네이티브 폼 제출(method·action)을 쓴다. onSubmit에서 preventDefault 후 서버 함수를 부른다"
-		});
 	}
-	if (has("requestPayment(") && !has("Origin")) findings.push({
-		ruleId: "parent-origin",
+	if (has("startPayment(") && !has("@sayren/storefront-sdk/payments")) findings.push({
+		ruleId: "payment-browser-launch",
+		file: "(프로젝트 전체)",
+		detail: "결제를 시작하지만 `@sayren/storefront-sdk/payments`로 결제창을 여는 코드가 없다"
+	});
+	const opensPayment = matches(/\bpayments\.open\(|\.open\(\s*(start|paymentStart)\b/);
+	if (opensPayment && !has("prepareWindow(")) findings.push({
+		ruleId: "payment-popup-prepare",
+		file: opensPayment.path,
+		detail: "받아 둔 결제 시작 값으로 결제창을 열지만 클릭 시점에 `payments.prepareWindow()`로 창을 먼저 여는 코드가 없다"
+	});
+	const fixedReturnUrl = matches(/returnUrl\s*[:=]\s*["'`]https?:\/\//);
+	if (fixedReturnUrl) findings.push({
+		ruleId: "checkout-origin",
+		file: fixedReturnUrl.path,
+		detail: "복귀 주소를 고정 문자열로 두었다. 배포된 주소(요청 origin)에서 만들고 그 도메인을 결제 도메인에 등록한다"
+	});
+	if (has("startPayment(") && !has(".result(")) findings.push({
+		ruleId: "payment-return-route",
 		file: "(프로젝트 전체)",
-		detail: "결제 요청에 Origin 헤더를 싣는 코드가 없다"
+		detail: "결제 복귀 화면에서 `payments.result()`를 부르는 코드가 없다"
 	});
-	if (has("requestPayment(") && !has("getStatus(")) findings.push({
-		ruleId: "closed-not-failed",
+	if (has(".result(") && !has("PROCESSING")) findings.push({
+		ruleId: "payment-processing-status",
 		file: "(프로젝트 전체)",
-		detail: "팝업이 결과 없이 닫힌 경우 결제 상태를 조회하는 코드가 없다"
+		detail: "결과 확인 중(`PROCESSING`)일 때 결제 상태를 다시 조회하는 코드가 없다"
 	});
 	if (has("createStorefrontClient(") && !has("@sayren/storefront-sdk/analytics")) findings.push({
 		ruleId: "analytics-start",
@@ -701,8 +700,8 @@ server.registerTool("get_scaffold_plan", {
 			}
 		],
 		doNotTouch: [
-			"src/lib/payment-popup.ts — 결제 팝업 규칙",
-			"src/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin·방문 식별 쿠키",
+			"src/lib/payments.ts·src/routes/checkout.return.tsx — 결제창 열기와 결제 복귀 결과 확인(브라우저)",
+			"src/lib/api.server.ts — 테넌트 헤더·토큰 전달·방문 식별 쿠키",
 			"src/lib/session.server.ts·src/start.ts — 구매자 세션 쿠키와 요청마다 한 번 하는 토큰 갱신",
 			"src/lib/analytics.ts — 방문 분석 시작(브라우저 한 번)과 시작 전 이벤트 큐",
 			"라우트 loader가 서버 함수(createServerFn)로 데이터를 받는 구조"
@@ -823,7 +822,7 @@ server.registerTool("call_api_write", {
 }, async (input) => invoke("write", input));
 server.registerTool("verify_storefront", {
 	title: "생성 결과 검증",
-	description: "만들어진 프로젝트를 규칙과 대조한다. 결제가 조용히 실패하는 실수(브라우저 번들의 process.env, 팝업 origin 미검증, 부모 origin 누락 등)를 잡는다.",
+	description: "만들어진 프로젝트를 규칙과 대조한다. 결제가 조용히 실패하는 실수(브라우저 번들의 process.env, 클릭 시점 팝업 선오픈 누락, 결제 복귀 화면의 결과 확인 누락, 결과 확인 중 상태 조회 누락 등)를 잡는다.",
 	inputSchema: { projectDir: z.string().describe("검사할 프로젝트 경로(절대 경로)") }
 }, async ({ projectDir }) => {
 	const files = await collectSources(projectDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "sayren-mcp": "./dist/index.mjs"
@@ -12,8 +12,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
     "zod": "^4.6.5",
-    "@sayren/store-sdk": "^0.7.0",
-    "@sayren/storefront-sdk": "^0.7.0"
+    "@sayren/storefront-sdk": "^0.8.0",
+    "@sayren/store-sdk": "^0.8.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -7,8 +7,8 @@
     "zod": "^4.6.5"
   },
   "versions": {
-    "@sayren/store-sdk": "0.7.0",
-    "@sayren/storefront-sdk": "0.7.0",
+    "@sayren/store-sdk": "0.8.0",
+    "@sayren/storefront-sdk": "0.8.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -1,7 +1,7 @@
 # 스토어프론트 템플릿 (TanStack Router · TanStack Start SSR)
 
 sayren MCP가 내려주는 스토어프론트 시작점이다. 구매 흐름 전체가 이미 붙어 있다.
-홈, 목록·검색, 상세, 장바구니, 주문서·결제 팝업, 완료, 로그인, 주문 내역이다.
+홈, 목록·검색, 상세, 장바구니, 주문서·결제(결제수단 선택 → 결제창 → 결제 복귀), 완료, 로그인, 주문 내역이다.
 
 ## 시작하기
 
@@ -54,16 +54,19 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
 
 ## 건드리지 않는 편이 좋은 것
 
-- `src/lib/payment-popup.ts` — 결제 팝업 규칙이다. 팝업은 클릭 콜스택에서 동기적으로 열고,
-  postMessage는 origin과 source를 모두 검증하며, 결과 없이 닫히면 서버에 상태를 물어본다.
-  하나라도 어기면 결제가 조용히 실패한다.
+- `src/lib/payments.ts`·`src/routes/checkout.return.tsx` — 결제 흐름이다. 결제 시작은 서버 함수로 하고
+  (구매자 토큰이 브라우저 JS에 나가지 않는다), 결제창은 결제 서비스가 그린다. 주문서는 버튼 클릭 시점에
+  `payments.prepareWindow()`로 빈 팝업을 먼저 열고(팝업 차단 회피) `payments.open(start, { window })`으로 결제창을
+  띄운다. 모바일·팝업 차단은 같은 탭이 결제 서비스로 이동하고 복귀 화면으로 돌아온다. 복귀 화면은
+  `payments.result()`로 결과를 읽는다. 결과를 모르면(`PROCESSING`) 실패로 단정하지 않고 결제 상태를 계속 조회한다 —
+  다시 결제하게 하면 이중 결제가 난다.
 - `src/lib/api.server.ts` — 테넌트 헤더와 토큰 전달 방식이다. 토큰을 모듈 전역에 담으면 서버 렌더에서
   다른 사용자의 요청에 섞인다.
 - `src/lib/session.server.ts`·`src/start.ts` — 구매자 세션 쿠키와 갱신이다. 갱신은 요청마다 한 번이고, 같은
   리프레시 토큰의 동시 갱신은 한 번으로 모은다. 리프레시 토큰은 한 번 쓰면 폐기되므로 각자 갱신하면 로그아웃된다.
 - loader가 서버 함수로 데이터를 받아 그리는 구조 — 컴포넌트에서 다시 받으면 검색 노출과 첫 화면이 죽는다.
-- 주문서 제출 방식 — `onSubmit`에서 `preventDefault` 후 서버 함수를 부른다. 네이티브 폼 제출은 문서를 다시 불러
-  열어 둔 결제 팝업의 제어를 잃는다.
+- 결제 도메인 — 실결제는 셀러 콘솔 설정 › 결제의 **결제 도메인**에 등록한 도메인에서만 된다. 이 쇼핑몰을 배포한 주소를
+  등록하고, 같은 주소를 PG(토스페이먼츠·포트원) 가맹 정보에도 등록한다. 테스트 결제는 localhost에서도 된다.
 
 ## 주의
 

package/template/src/lib/api.server.ts

@@ -28,13 +28,6 @@ export function apiFor(
     cartToken: options.cartToken ?? undefined,
     onCartToken: options.onCartToken,
     ...analyticsIdsFromCookie(request.headers.get("cookie")),
-    // 결제 요청에 우리 화면의 origin을 실어 보낸다. 결제 팝업은 이 값으로만 부모 창에
-    // 결과를 알린다 — 빠지면 결제는 되지만 주문서가 완료를 못 받는다.
-    fetch: (input, init) => {
-      const headers = new Headers(init?.headers);
-      headers.set("Origin", new URL(request.url).origin);
-      return fetch(input, { ...init, headers });
-    },
   });
 }
 

package/template/src/lib/api.ts

@@ -1,7 +1,7 @@
 import { createStorefrontClient } from "@sayren/storefront-sdk";
 import type { PublicConfig } from "./config";
 
-/** 브라우저용 — 서버 함수가 내려준 설정으로 만든다(결제 상태 폴링에 쓴다) */
+/** 브라우저용 — 서버 함수가 내려준 설정으로 만든다(결제창·결제 승인·결제 상태 조회에 쓴다) */
 export function browserApi(config: PublicConfig) {
   return createStorefrontClient({ baseUrl: config.apiBaseUrl, storeCode: config.storeCode });
 }

package/template/src/lib/payments.ts

@@ -0,0 +1,31 @@
+import { createPayments, type Payments } from "@sayren/storefront-sdk/payments";
+import { browserApi } from "./api";
+import type { PublicConfig } from "./config";
+
+/**
+ * 결제 — 브라우저 전용. 이 파일은 그대로 두는 편이 좋다.
+ *
+ * 1. 결제 시작(`startPayment`)은 서버 함수에서 한다 — 구매자 토큰이 브라우저 JS에 노출되지 않는다.
+ * 2. 결제창은 결제 서비스가 그린다. 버튼 클릭 시점에 `payments.prepareWindow()`로 빈 팝업을 먼저 열고
+ *    (팝업 차단 회피), 서버 함수가 돌려준 결제 시작 값으로 `payments.open(start, { window })`을 부른다.
+ * 3. 모바일이나 팝업 차단이면 같은 탭이 결제 서비스로 이동하고, 결제가 끝나면 복귀 화면(`/checkout/return`)으로
+ *    돌아온다. 복귀 화면은 `payments.result()` 한 줄로 결과를 읽는다.
+ * 4. 결과를 모르면(`PROCESSING`) 실패로 단정하지 말고 계속 조회한다 — 다시 결제하게 하면 이중 결제가 난다.
+ * 5. 복귀 주소의 도메인을 셀러 콘솔 설정 › 결제의 결제 도메인에 등록한다(테스트 결제는 localhost 허용).
+ */
+/**
+ * 설정마다 하나만 만든다. `prepareWindow()`로 연 창과 그 결과를 기다리는 감시가 같은 인스턴스에 묶여 있어서,
+ * 화면마다 새로 만들면 미리 연 창을 `open()`이 받지 못하고 이전 결제의 감시도 정리되지 않는다.
+ */
+let cached: { key: string; payments: Payments } | null = null;
+
+export function paymentsFor(config: PublicConfig): Payments {
+  const key = `${config.apiBaseUrl}\u0000${config.storeCode}`;
+  if (cached?.key !== key) {
+    cached = { key, payments: createPayments({ client: browserApi(config) }) };
+  }
+  return cached.payments;
+}
+
+/** 결제 복귀 경로 — 주문서가 결제 시작 때 복귀 주소로 보낸다 */
+export const PAYMENT_RETURN_PATH = "/checkout/return";

package/template/src/routeTree.gen.ts

@@ -16,6 +16,7 @@ import { Route as LoginRouteImport } from './routes/login'
 import { Route as AuthCallbackRouteImport } from './routes/auth.callback'
 import { Route as CheckoutIndexRouteImport } from './routes/checkout.index'
 import { Route as CheckoutCompleteRouteImport } from './routes/checkout.complete'
+import { Route as CheckoutReturnRouteImport } from './routes/checkout.return'
 import { Route as OrdersIndexRouteImport } from './routes/orders.index'
 import { Route as OrdersOrderIdRouteImport } from './routes/orders.$orderId'
 import { Route as ProductsIndexRouteImport } from './routes/products.index'
@@ -56,6 +57,11 @@ const CheckoutCompleteRoute = CheckoutCompleteRouteImport.update({
   path: '/checkout/complete',
   getParentRoute: () => rootRouteImport,
 } as any)
+const CheckoutReturnRoute = CheckoutReturnRouteImport.update({
+  id: '/checkout/return',
+  path: '/checkout/return',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const OrdersIndexRoute = OrdersIndexRouteImport.update({
   id: '/orders/',
   path: '/orders/',
@@ -84,6 +90,7 @@ export interface FileRoutesByFullPath {
   '/login': typeof LoginRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/checkout/complete': typeof CheckoutCompleteRoute
+  '/checkout/return': typeof CheckoutReturnRoute
   '/orders/$orderId': typeof OrdersOrderIdRoute
   '/products/$productId': typeof ProductsProductIdRoute
   '/checkout/': typeof CheckoutIndexRoute
@@ -97,6 +104,7 @@ export interface FileRoutesByTo {
   '/login': typeof LoginRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/checkout/complete': typeof CheckoutCompleteRoute
+  '/checkout/return': typeof CheckoutReturnRoute
   '/orders/$orderId': typeof OrdersOrderIdRoute
   '/products/$productId': typeof ProductsProductIdRoute
   '/checkout': typeof CheckoutIndexRoute
@@ -111,6 +119,7 @@ export interface FileRoutesById {
   '/login': typeof LoginRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/checkout/complete': typeof CheckoutCompleteRoute
+  '/checkout/return': typeof CheckoutReturnRoute
   '/orders/$orderId': typeof OrdersOrderIdRoute
   '/products/$productId': typeof ProductsProductIdRoute
   '/checkout/': typeof CheckoutIndexRoute
@@ -126,6 +135,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/auth/callback'
     | '/checkout/complete'
+    | '/checkout/return'
     | '/orders/$orderId'
     | '/products/$productId'
     | '/checkout/'
@@ -139,6 +149,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/auth/callback'
     | '/checkout/complete'
+    | '/checkout/return'
     | '/orders/$orderId'
     | '/products/$productId'
     | '/checkout'
@@ -152,6 +163,7 @@ export interface FileRouteTypes {
     | '/login'
     | '/auth/callback'
     | '/checkout/complete'
+    | '/checkout/return'
     | '/orders/$orderId'
     | '/products/$productId'
     | '/checkout/'
@@ -166,6 +178,7 @@ export interface RootRouteChildren {
   LoginRoute: typeof LoginRoute
   AuthCallbackRoute: typeof AuthCallbackRoute
   CheckoutCompleteRoute: typeof CheckoutCompleteRoute
+  CheckoutReturnRoute: typeof CheckoutReturnRoute
   OrdersOrderIdRoute: typeof OrdersOrderIdRoute
   ProductsProductIdRoute: typeof ProductsProductIdRoute
   CheckoutIndexRoute: typeof CheckoutIndexRoute
@@ -224,6 +237,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof CheckoutCompleteRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/checkout/return': {
+      id: '/checkout/return'
+      path: '/checkout/return'
+      fullPath: '/checkout/return'
+      preLoaderRoute: typeof CheckoutReturnRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/orders/': {
       id: '/orders/'
       path: '/orders'
@@ -262,6 +282,7 @@ const rootRouteChildren: RootRouteChildren = {
   LoginRoute: LoginRoute,
   AuthCallbackRoute: AuthCallbackRoute,
   CheckoutCompleteRoute: CheckoutCompleteRoute,
+  CheckoutReturnRoute: CheckoutReturnRoute,
   OrdersOrderIdRoute: OrdersOrderIdRoute,
   ProductsProductIdRoute: ProductsProductIdRoute,
   CheckoutIndexRoute: CheckoutIndexRoute,

package/template/src/routes/checkout.index.tsx

@@ -1,17 +1,23 @@
-import { ApiError } from "@sayren/storefront-sdk";
+import {
+  ApiError,
+  paymentOptionKey,
+  paymentOptionSchema,
+  paymentStartSchema,
+} from "@sayren/storefront-sdk";
+import type { PaymentResult } from "@sayren/storefront-sdk/payments";
 import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
-import { useRef, useState } from "react";
+import { getRequestUrl } from "@tanstack/react-start/server";
+import { useState } from "react";
 import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
-import { browserApi } from "../lib/api";
 import { apiFor } from "../lib/api.server";
 import { readCartToken } from "../lib/cart-session.server";
 import { checkoutIntentFrom, checkoutSearch } from "../lib/checkout-intent";
 import type { PublicConfig } from "../lib/config";
 import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
 import { formatPrice } from "../lib/format";
-import { createPaymentPopup, type PaymentPopup } from "../lib/payment-popup";
+import { PAYMENT_RETURN_PATH, paymentsFor } from "../lib/payments";
 import { readToken } from "../lib/session.server";
 
 const createCheckout = createServerFn({ method: "POST" })
@@ -43,6 +49,9 @@ const createCheckout = createServerFn({ method: "POST" })
 
 const paymentForm = z.object({
   checkoutId: z.string(),
+  option: paymentOptionSchema,
+  /** 결제에 실패하면 돌아올 주문서 주소 */
+  back: z.string(),
   receiverName: z.string(),
   phone: z.string(),
   zipCode: z.string(),
@@ -54,35 +63,59 @@ const paymentForm = z.object({
   orderPassword: z.string(),
 });
 
-/** 결제 요청은 서버에서 한다 — 토큰이 브라우저 JS에 노출되지 않는다 */
-const requestPayment = createServerFn({ method: "POST" })
+/** 결제 시작은 서버에서 한다 — 토큰이 브라우저 JS에 노출되지 않는다. 결제창 호출 값(공개 값)만 내려준다 */
+const startPayment = createServerFn({ method: "POST" })
   .validator(paymentForm)
   .handler(async ({ data }) => {
     const accessToken = readToken();
     const api = apiFor({ accessToken, cartToken: readCartToken() });
-    const payment = await api.checkout.requestPayment(data.checkoutId, {
-      shippingAddress: {
-        receiverName: data.receiverName,
-        phone: data.phone,
-        zipCode: data.zipCode,
-        address1: data.address1,
-        address2: data.address2 || undefined,
-        deliveryMemo: data.deliveryMemo || undefined,
-      },
-      paymentMethod: "CARD",
-      guest: accessToken
-        ? undefined
-        : {
-            name: data.guestName,
-            phone: data.phone,
-            email: data.email,
-            orderPassword: data.orderPassword,
-          },
-    });
-    // 브라우저에는 팝업 주소와 상태 조회 키만 내려준다
-    return { paymentId: payment.paymentId, popupUrl: payment.pgParams.popupUrl };
+    // 복귀 주소 — 이 도메인이 셀러 콘솔 결제 도메인에 있어야 한다(테스트 결제는 localhost 허용)
+    const returnUrl = new URL(PAYMENT_RETURN_PATH, new URL(getRequestUrl()).origin);
+    returnUrl.searchParams.set("back", data.back);
+    try {
+      const start = await api.checkout.startPayment(data.checkoutId, {
+        option: data.option,
+        returnUrl: returnUrl.toString(),
+        shippingAddress: {
+          receiverName: data.receiverName,
+          phone: data.phone,
+          zipCode: data.zipCode,
+          address1: data.address1,
+          address2: data.address2 || undefined,
+          deliveryMemo: data.deliveryMemo || undefined,
+        },
+        guest: accessToken
+          ? undefined
+          : {
+              name: data.guestName,
+              phone: data.phone,
+              email: data.email,
+              orderPassword: data.orderPassword,
+            },
+      });
+      // 결제 시작 값은 JSON으로 넘기고 브라우저에서 SDK 스키마로 다시 읽는다 — 서버 함수 직렬화 타입에 맞춘다
+      return { start: JSON.stringify(start), error: null };
+    } catch (error) {
+      return { start: null, error: startErrorMessage(error) };
+    }
   });
 
+function startErrorMessage(error: unknown): string {
+  if (!(error instanceof ApiError)) return "결제를 시작하지 못했어요. 잠시 후 다시 시도해주세요.";
+  switch (error.code) {
+    case "PAYMENT_OPTION_UNAVAILABLE":
+      return "지금 쓸 수 없는 결제수단이에요. 다른 결제수단을 골라주세요.";
+    case "PAYMENT_PROVIDER_UNAVAILABLE":
+      return "결제창을 준비하지 못했어요. 다른 결제수단으로 시도해주세요.";
+    case "PAYMENT_NOT_CONFIGURED":
+      return "결제 수단을 준비하고 있어요. 잠시 후 다시 시도해주세요.";
+    case "RETURN_URL_NOT_ALLOWED":
+      return "이 쇼핑몰 주소에서는 결제할 수 없어요. 셀러 콘솔 설정 › 결제에서 결제 도메인을 확인해주세요.";
+    default:
+      return "결제를 시작하지 못했어요. 입력한 내용을 확인하고 다시 시도해주세요.";
+  }
+}
+
 export const Route = createFileRoute("/checkout/")({
   validateSearch: checkoutSearch,
   loaderDeps: ({ search }) => search,
@@ -94,54 +127,58 @@ export const Route = createFileRoute("/checkout/")({
 function Checkout() {
   const { checkout, member, config } = Route.useLoaderData();
   const navigate = useNavigate();
-  const popupRef = useRef<PaymentPopup | null>(null);
   const [notice, setNotice] = useState<string | null>(null);
-  const [checking, setChecking] = useState(false);
   const [submitting, setSubmitting] = useState(false);
+  const options = checkout.paymentOptions;
+  const [selected, setSelected] = useState(options[0] ? paymentOptionKey(options[0]) : "");
+
+  const settle = (result: PaymentResult, back: string) => {
+    if (result.status === "COMPLETED") {
+      void navigate({
+        to: "/checkout/complete",
+        search: { orderId: result.orderId },
+        replace: true,
+      });
+      return;
+    }
+    if (result.status === "PROCESSING") {
+      // 결과 확인 중 — 복귀 화면이 결제 상태를 확정할 때까지 조회한다
+      void navigate({
+        to: "/checkout/return",
+        search: { back, sayrenPaymentId: result.paymentId },
+        replace: true,
+      });
+      return;
+    }
+    setNotice(
+      result.status === "CANCELED"
+        ? "결제를 취소했어요. 다른 결제수단으로 다시 시도해주세요."
+        : result.status === "FAILED"
+          ? result.message
+          : "결제 결과를 확인하지 못했어요. 주문 내역을 확인해주세요.",
+    );
+  };
 
   const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
-    // 문서를 다시 부르지 않는다 — 팝업 제어 상태가 사라진다
     event.preventDefault();
+    const option = options.find((item) => paymentOptionKey(item) === selected);
+    if (!option) {
+      setNotice("결제수단을 골라주세요.");
+      return;
+    }
     const form = new FormData(event.currentTarget);
     const field = (name: string) => String(form.get(name) ?? "");
-    let paymentId: string | null = null;
-
-    // 클릭 콜스택에서 동기적으로 연다 — 응답을 기다린 뒤 열면 차단된다
-    const popup = createPaymentPopup({
-      onCompleted: (message) => {
-        if (message.orderId) {
-          void navigate({ to: "/checkout/complete", search: { orderId: message.orderId } });
-        } else {
-          setNotice("결제가 완료됐어요. 주문 내역에서 확인해주세요.");
-        }
-      },
-      onFailed: (message) => {
-        setNotice(message.message ?? "결제가 실패했어요. 다시 시도해주세요.");
-      },
-      onClosed: () => {
-        // 닫혔다고 실패로 단정하지 않는다 — 서버에 결제 상태를 물어본다
-        if (!paymentId) return;
-        setChecking(true);
-        void pollPaymentStatus(config, paymentId).then((status) => {
-          setChecking(false);
-          if (status?.status === "completed" && status.orderId) {
-            void navigate({ to: "/checkout/complete", search: { orderId: status.orderId } });
-          } else {
-            setNotice("결제창이 닫혔어요. 결제를 마쳤다면 잠시 뒤 주문 내역에서 확인해주세요.");
-          }
-        });
-      },
-    });
-    popupRef.current?.close();
-    popupRef.current = popup;
-    popup.open();
-
-    // 결제 요청 응답이 오면 이미 열어 둔 팝업을 결제 주소로 보낸다
+    const back = window.location.pathname + window.location.search;
+    const payments = paymentsFor(config);
+    // 결제창은 클릭 시점에 열어야 팝업 차단에 걸리지 않는다 — 서버 함수를 기다리기 전에 빈 창을 먼저 연다
+    const paymentWindow = payments.prepareWindow();
     setSubmitting(true);
     setNotice(null);
-    requestPayment({
+    void startPayment({
       data: {
         checkoutId: checkout.checkoutId,
+        option,
+        back,
         receiverName: field("receiverName"),
         phone: field("phone"),
         zipCode: field("zipCode"),
@@ -153,16 +190,23 @@ function Checkout() {
         orderPassword: field("orderPassword"),
       },
     })
-      .then((payment) => {
-        paymentId = payment.paymentId;
-        if (!popup.navigate(payment.popupUrl)) {
-          popup.close();
-          setNotice("결제창이 열리지 않았어요. 팝업 차단을 풀고 다시 시도해주세요.");
+      .then(async ({ start, error }) => {
+        if (!start) {
+          paymentWindow.close();
+          setNotice(error);
+          return;
         }
+        // 결제 서비스가 결제창을 그린다. 팝업이면 결과를 여기서 받고, 리다이렉트면 이 탭이 떠난다
+        settle(
+          await payments.open(paymentStartSchema.parse(JSON.parse(start)), {
+            window: paymentWindow,
+          }),
+          back,
+        );
       })
       .catch(() => {
-        popup.close();
-        setNotice("결제를 시작하지 못했어요. 입력한 내용을 확인하고 다시 시도해주세요.");
+        paymentWindow.close();
+        setNotice("결제를 시작하지 못했어요. 잠시 후 다시 시도해주세요.");
       })
       .finally(() => setSubmitting(false));
   };
@@ -195,13 +239,45 @@ function Checkout() {
           </section>
         )}
 
+        <fieldset className="space-y-2">
+          <legend className="mb-3 font-bold text-lg">결제수단</legend>
+          {options.length === 0 ? (
+            <p className="text-muted text-sm">지금 결제할 수 있는 결제수단이 없어요.</p>
+          ) : (
+            <div className="grid grid-cols-2 gap-2">
+              {options.map((option) => {
+                const key = paymentOptionKey(option);
+                return (
+                  <label
+                    key={key}
+                    className={`flex cursor-pointer flex-col rounded-md border px-3 py-2 text-sm ${
+                      selected === key ? "border-ink" : "border-line"
+                    }`}
+                  >
+                    <span className="flex items-center gap-2">
+                      <input
+                        type="radio"
+                        name="paymentOption"
+                        value={key}
+                        checked={selected === key}
+                        onChange={() => setSelected(key)}
+                      />
+                      <span className="font-medium">{option.label}</span>
+                    </span>
+                    <span className="pl-6 text-muted text-xs">{option.pgName}</span>
+                  </label>
+                );
+              })}
+            </div>
+          )}
+        </fieldset>
+
         <SubmitButton
-          disabled={submitting}
+          disabled={submitting || options.length === 0}
           className="h-12 w-full rounded-md bg-ink font-semibold text-white disabled:opacity-50"
         >
           {formatPrice(checkout.amounts.totalAmount)} 결제하기
         </SubmitButton>
-        <p className="text-center text-muted text-xs">결제창은 새 팝업에서 열려요</p>
       </form>
 
       <aside className="space-y-4 rounded-lg border border-line p-5">
@@ -236,24 +312,12 @@ function Checkout() {
             테스트 결제예요. 실제로 돈이 오가지 않아요.
           </p>
         ) : null}
-        {checking ? <p className="text-muted text-sm">결제 상태를 확인하고 있어요…</p> : null}
         {notice ? <p className="rounded-md bg-chip px-3 py-2 text-sm">{notice}</p> : null}
       </aside>
     </div>
   );
 }
 
-/** 팝업이 결과 없이 닫힌 경우 — 서버 상태가 진실이다 */
-async function pollPaymentStatus(config: PublicConfig, paymentId: string) {
-  const api = browserApi(config);
-  for (let attempt = 0; attempt < 6; attempt += 1) {
-    const status = await api.payments.getStatus(paymentId).catch(() => null);
-    if (status && status.status !== "pending" && status.status !== "processing") return status;
-    await new Promise((resolve) => setTimeout(resolve, 1500));
-  }
-  return null;
-}
-
 function Field({
   label,
   name,

package/template/src/routes/checkout.return.tsx

@@ -0,0 +1,143 @@
+import type { PaymentResult } from "@sayren/storefront-sdk/payments";
+import { createFileRoute, Link, useNavigate } from "@tanstack/react-router";
+import { createServerFn } from "@tanstack/react-start";
+import { useEffect, useState } from "react";
+import { z } from "zod";
+import type { PublicConfig } from "../lib/config";
+import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import { paymentsFor } from "../lib/payments";
+import { safeRedirect } from "../lib/safe-redirect";
+
+// `back`은 결제 서비스를 거쳐 돌아오는 값이라 누구나 바꿀 수 있다 — 같은 사이트 경로만 쓴다(열린 리다이렉트·javascript: 방지)
+const returnSearch = z.object({
+  back: z
+    .string()
+    .optional()
+    .catch(undefined)
+    .transform((value) =>
+      value !== undefined && safeRedirect(value) === value ? value : undefined,
+    ),
+  /** 결제 서비스가 붙이는 결제 id — SDK가 주소에서 읽으므로 주소에 그대로 남긴다 */
+  sayrenPaymentId: z.string().optional().catch(undefined),
+  /** 참고용 결과 — 결과의 원천은 결제 상태 조회다 */
+  sayrenResult: z.string().optional().catch(undefined),
+});
+
+const getConfig = createServerFn({ method: "GET" }).handler(
+  (): PublicConfig => ({ apiBaseUrl: API_BASE_URL, storeCode: resolveStoreCode() }),
+);
+
+/** 결과 확인 중일 때 상태를 다시 보는 간격과 횟수 */
+const POLL_MS = 2000;
+const POLL_TIMES = 15;
+
+type View =
+  | { kind: "working" }
+  | { kind: "processing" }
+  | { kind: "failed"; canceled: boolean; message: string }
+  | { kind: "unknown" };
+
+/**
+ * 결제 복귀 화면 — 결제 서비스가 리다이렉트 결제를 마치고 돌려보내는 곳이다. 결과는 주소의 결제 id로
+ * 결제 상태를 조회해 정한다(`payments.result`). 같은 주소로 다시 열어도(뒤로 가기·새로고침) 안전하다.
+ */
+export const Route = createFileRoute("/checkout/return")({
+  validateSearch: returnSearch,
+  loader: () => getConfig(),
+  // 복귀 주소의 결제 id가 외부 리소스 요청의 Referer로 새지 않게 한다
+  head: () => ({ meta: [{ title: "결제 확인" }, { name: "referrer", content: "no-referrer" }] }),
+  component: PaymentReturn,
+});
+
+function PaymentReturn() {
+  const config = Route.useLoaderData();
+  const { back } = Route.useSearch();
+  const navigate = useNavigate();
+  const [view, setView] = useState<View>({ kind: "working" });
+
+  useEffect(() => {
+    let active = true;
+    const payments = paymentsFor(config);
+    const done = (orderId: string) =>
+      void navigate({ to: "/checkout/complete", search: { orderId }, replace: true });
+
+    const show = (result: PaymentResult): boolean => {
+      if (result.status === "COMPLETED") {
+        done(result.orderId);
+        return true;
+      }
+      if (result.status === "CANCELED" || result.status === "FAILED") {
+        setView({
+          kind: "failed",
+          canceled: result.status === "CANCELED",
+          message: result.message,
+        });
+        return true;
+      }
+      if (result.status === "INVALID") {
+        setView({ kind: "unknown" });
+        return true;
+      }
+      return false;
+    };
+
+    const run = async () => {
+      const first = await payments.result(window.location.href).catch(() => null);
+      if (!active) return;
+      if (first && show(first)) return;
+      // 결과 확인 중 — 실패로 단정하지 않고 결제 상태를 다시 조회한다
+      setView({ kind: "processing" });
+      for (let i = 0; i < POLL_TIMES && active; i += 1) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+        if (!active) return;
+        const next = await payments.result(window.location.href).catch(() => null);
+        if (!active) return;
+        if (next && show(next)) return;
+      }
+      if (active) setView({ kind: "unknown" });
+    };
+
+    void run();
+    return () => {
+      active = false;
+    };
+  }, [config, navigate]);
+
+  return (
+    <div className="mx-auto max-w-md space-y-6 py-16 text-center">
+      {view.kind === "working" || view.kind === "processing" ? (
+        <>
+          <h1 className="font-bold text-2xl">결제를 확인하고 있어요</h1>
+          <p className="text-muted text-sm">
+            {view.kind === "processing"
+              ? "결제사에서 결과를 확인하는 중이에요. 이 화면을 닫지 말고 잠시만 기다려주세요."
+              : "잠시만 기다려주세요."}
+          </p>
+        </>
+      ) : view.kind === "failed" ? (
+        <>
+          <h1 className="font-bold text-2xl">
+            {view.canceled ? "결제를 취소했어요" : "결제하지 못했어요"}
+          </h1>
+          {view.canceled ? null : <p className="text-muted text-sm">{view.message}</p>}
+          <div className="flex justify-center gap-2">
+            <a href={back ?? "/cart"} className="rounded-md bg-ink px-5 py-3 text-white">
+              다른 결제수단으로 다시 결제
+            </a>
+          </div>
+        </>
+      ) : (
+        <>
+          <h1 className="font-bold text-2xl">결제 결과를 확인하지 못했어요</h1>
+          <p className="text-muted text-sm">
+            결제를 마쳤다면 잠시 뒤 주문 내역에 나타나요. 다시 결제하기 전에 주문 내역을 먼저
+            확인해주세요.
+          </p>
+          <Link to="/orders" className="inline-block rounded-md border border-ink px-5 py-3">
+            주문 내역
+          </Link>
+        </>
+      )}
+    </div>
+  );
+}

package/template/src/lib/payment-popup.ts

@@ -1,98 +0,0 @@
-/**
- * Hosted Checkout 결제 팝업 — 이 파일은 그대로 두는 편이 좋다. 규칙을 하나라도 어기면
- * 결제가 조용히 실패한다.
- *
- * 1. 팝업은 **클릭 콜스택에서 동기적으로** 연다. API 응답을 기다린 뒤에 열면 브라우저가 막는다.
- *    그래서 빈 창을 먼저 열고 `navigate`로 결제 주소를 넣는다.
- * 2. 팝업이 보내는 postMessage는 `event.origin`과 `event.source`를 **모두** 검증한다.
- * 3. 결과 메시지 없이 창이 닫히면 결제가 끝났는지 알 수 없다. 이때는 실패로 단정하지 말고
- *    서버에 결제 상태를 물어본다(주문서 화면이 폴링한다).
- */
-export const PAYMENT_POPUP_NAME = "sayren-checkout";
-const PAYMENT_POPUP_FEATURES = "width=460,height=680";
-const CLOSE_POLL_MS = 500;
-
-export interface PaymentCompletedMessage {
-  type: "payment:completed";
-  paymentId: string;
-  /** 결제는 끝났지만 팝업이 주문번호를 모를 수 있다 — 이때는 주문 내역을 안내한다 */
-  orderId: string | null;
-}
-
-export interface PaymentFailedMessage {
-  type: "payment:failed";
-  paymentId?: string;
-  code?: string;
-  message?: string;
-}
-
-export interface PaymentPopupHandlers {
-  onCompleted: (message: PaymentCompletedMessage) => void;
-  onFailed: (message: PaymentFailedMessage) => void;
-  /** 결과 메시지 없이 닫혔다 — 실패가 아니라 "모른다"는 뜻이다 */
-  onClosed: () => void;
-}
-
-export interface PaymentPopup {
-  /** 클릭 즉시 부른다. 차단되면 null */
-  open: () => Window | null;
-  /** 결제 주소를 받은 뒤 부른다. 팝업이 없거나 닫혔으면 false */
-  navigate: (popupUrl: string) => boolean;
-  close: () => void;
-}
-
-export function createPaymentPopup(handlers: PaymentPopupHandlers): PaymentPopup {
-  let popup: Window | null = null;
-  let listener: ((event: MessageEvent) => void) | null = null;
-  let timer: ReturnType<typeof setInterval> | null = null;
-
-  const stop = () => {
-    if (listener) window.removeEventListener("message", listener);
-    listener = null;
-    if (timer) clearInterval(timer);
-    timer = null;
-  };
-
-  const watch = (origin: string) => {
-    stop();
-    listener = (event: MessageEvent) => {
-      if (event.origin !== origin) return;
-      if (event.source !== popup) return;
-      const data = event.data as PaymentCompletedMessage | PaymentFailedMessage | null;
-      if (!data || typeof data !== "object") return;
-      if (data.type === "payment:completed") {
-        stop();
-        handlers.onCompleted(data);
-      } else if (data.type === "payment:failed") {
-        stop();
-        handlers.onFailed(data);
-      }
-    };
-    window.addEventListener("message", listener);
-
-    timer = setInterval(() => {
-      if (popup?.closed) {
-        stop();
-        handlers.onClosed();
-      }
-    }, CLOSE_POLL_MS);
-  };
-
-  return {
-    open: () => {
-      popup = window.open("", PAYMENT_POPUP_NAME, PAYMENT_POPUP_FEATURES);
-      return popup;
-    },
-    navigate: (popupUrl) => {
-      if (!popup || popup.closed) return false;
-      popup.location.href = popupUrl;
-      watch(new URL(popupUrl).origin);
-      return true;
-    },
-    close: () => {
-      stop();
-      popup?.close();
-      popup = null;
-    },
-  };
-}