Environment Configuration — Nougat DevPay

FE (Nuxt runtimeConfig.public)

Var	Prod	Staging	용도
NUXT_PUBLIC_SITE_URL	https://devpay.chu.plus	https://staging.devpay.chu.plus	위젯 embed base·공유 링크
NUXT_PUBLIC_API_BASE	https://api.devpay.chu.plus	https://api.staging.devpay.chu.plus	API upstream
NUXT_PUBLIC_DATA_MODE	api	api	api=서버 권위, mock=로컬 데모
NUXT_PUBLIC_MCP_URL	(미설정)	(미설정)	MCP 안내 — 준비 중

Var	위치	용도
DEV_AUTH	staging [vars]=1	staging만 X-Dev-User 허용
NOUGAT_API_SECRET	prod wrangler secret	prod Bearer 인증
NOUGAT_AUDIT_HMAC_KEY	prod wrangler secret	audit 무결성 체인 키
CORS_ALLOWED_ORIGINS	(미설정=기본 4도메인)	쉼표 allowlist
PAYMENT_PROVIDER	[vars] 기본 `mock`	결제 프로바이더 — `mock`/`toss`/`portone`(미구현 슬롯)
PAYMENT_LIVE_ENABLED	[vars] 기본 `false`	hard guard — `true`이면 toss 어댑터 초기화 거부 (live 미지원)
TOSS_CLIENT_KEY	[vars]	Toss 클라이언트 키 — `test_ck_`/`test_gck_`만 허용
TOSS_SECRET_KEY	wrangler secret	Toss 시크릿 — `test_sk_`만 허용 (`live_sk_` 감지 시 어댑터 거부, 로그에 키 원문 금지)
TOSS_WEBHOOK_SECRET	wrangler secret (선택)	개발자센터 웹훅 보안 키 — 설정 시 `tosspayments-webhook-signature` HMAC 검증 필수화
TOSS_API_BASE	[vars] (선택)	기본 `https://api.tosspayments.com` — 로컬 스텁 테스트용 오버라이드
TOSS_SUCCESS_URL / TOSS_FAIL_URL	[vars] (선택)	checkout 응답의 위젯 리다이렉트 URL 폴백 (요청 바디가 우선)

provider=toss일 때 POST /api/v1/checkout은 pending 주문+결제를 만들고 {provider:"toss", toss:{client_key, order_id, order_name, amount, success_url, fail_url}}를 반환한다. FE가 결제위젯을 마운트해 successUrl로 paymentKey/orderId/amount를 받으면 POST /api/v1/checkout/confirm으로 승인을 확정한다.
paid 부수효과(원장/라이선스/구독)는 confirm 성공 또는 POST /api/v1/webhooks/toss reconcile 시점에만 발생한다. 불확실 응답(타임아웃/5xx)은 주문을 confirm_pending으로 남기고 GET /v1/payments/{paymentKey} 재조회로 회복한다.
환불은 Toss POST /v1/payments/{paymentKey}/cancel(cancelReason, 부분은 cancelAmount) 후에만 내부 효과를 적용하고, 불확실 결과는 refund_attempts.status='needs_review'로 남겨 다음 호출이 GET reconcile한다. 누적 부분 환불은 결제액을 넘지 않는다.
웹훅은 페이로드를 신뢰하지 않는다 — TOSS_WEBHOOK_SECRET 설정 시 HMAC 서명 검증 + 항상 GET 재조회한 Toss 상태만 권위로 삼는다. 실결제(live 키/PAYMENT_LIVE_ENABLED=true)는 이번 wave에서 지원하지 않으며 fail closed로 거부된다.