[Next.js] 결제 콜백 페이지 적용 중 serverRuntimeConfig를 다뤄보며..

📍 결제 콜백 페이지 적용 중 serverRuntimeConfig를 다뤄보며..

기존에 하나의 서비스에서만 사용하던 빌링 모듈을 인터파크와 놀 모두에서 사용할 수 있는 통합 빌링 모듈로 마이그레이션하는 작업을 진행했다. 이 과정에서 결제수단을 신용카드로 선택하면, 기존에 없던 이니시스(Inicis) 콜백 페이지가 새로 필요하게되었다. (기존에는 토스페이먼츠만 사용하고있었다.)

이니시스의 경우, 결제 콜백이 /api/payments/[id]/[paymentAgency]와 같은 API 라우터 내부에서 실행된다. 이 구조는 기존 토스페이먼츠와 달리 서버사이드에서만 동작하기 때문에 serverRuntimeConfig 환경변수를 사용하고있다.

---

✅ serverRuntimeConfig란?

serverRuntimeConfig란 서버 사이드에서만 접근 가능한 환경 변수 설정 방법이다. 다만 현재는 레거시로 간주되고 있으며, Next.js를 standalone 모드로 빌드할 경우 빌드시점의 값으로 고정된다. 또한 React server components에서는 작동하지않기 때문에 이 경우에는 environment variables 사용이 권장된다.

// next.config.js
module.exports = {
  serverRuntimeConfig: {
    // 서버사이드에서만 실행
    mySecret: 'secret',
    secondSecret: process.env.SECOND_SECRET, // Pass through env variables
  },
  publicRuntimeConfig: {
    // 서버 & 클라이언트 모두 실행 가능
    staticFolder: '/static',
  },
}

// index.tsx
import getConfig from 'next/config'
import Image from 'next/image'

// Only holds serverRuntimeConfig and publicRuntimeConfig
const { serverRuntimeConfig, publicRuntimeConfig } = getConfig()
// Will only be available on the server-side
console.log(serverRuntimeConfig.mySecret)
// Will be available on both server-side and client-side
console.log(publicRuntimeConfig.staticFolder)

function MyImage() {
  return (
    <div>
      <Image
        src={`${publicRuntimeConfig.staticFolder}/logo.png`}
        alt="logo"
        layout="fill"
      />
    </div>
  )
}

export MyImage

---

🧩 문제 상황: 서버사이드 환경변수 누락

여튼 문제가 되었던 코드는 다음과 같은데, 공통모듈내에서 결제승인 API를 요청하기위한 baseUrl을 다음처럼 설정한다. 이 함수는 토스페이먼츠(클라이언트사이드)와 이니시스(서버사이드) 모두에서 동일하게 호출하고 있고, 정상적으로 동작하고있어서 별다른 환경변수 설정이 필요없다고 생각했다. 하지만 DEV환경에서 테스트 중 결제승인 API가 호출되지 못한 현상이 발생했고 datadog에서 에러로그를 확인해보니 URL이 다음과 같이 잘못 생성되고 있었다.

// 환경변수를 제대로 불러오지 못했던 코드
const baseUrl = serverRuntimeConfig?.API_GATEWAY_URL ?? process.env.PAYMENT_PROXY_PATH
const url = `${baseUrl}/externals/v1/payments/...`

TypeError: Failed to parse URL from ${PAYMENT_PROXY_PATH}/tour-billing/externals/v1/payments/...

PAYMENT_PROXY_PATH는 단순하게 basePath/api routes였고, 처음엔 이게 왜 에러가 발생하는지 의문이었지만 결국 원인은 이 코드가 서버사이드에서 실행되면서 호스트 정보가 누락된 상태로 fetch를 시도한 것이었다.

---

🔧 해결 방법: apiGatewayUrl 환경변수 명시

// 환경변수를 설정하는 함수
export const withPaymentSdkEnv =
(options: WithPaymentSdkEnvOptions) =>
(nextConfig = {}) => {
  const env = {}

  return {
    ...nextConfig,
    env,
    serverRuntimeConfig: { 
      ...env, 
      API_GATEWAY_URL: options.apiGatewayUrl 
    }, // 도메인에서 apiGatewayUrl를 넣어주지않아 PAYMENT_PROXY_PATH를 리턴하였다.     
  }
}

클라이언트에서 호출하게되면 web-gateway를 거치기때문에 호스트 없이도 PAYMENT_PROXY_PATH를 통해 proxy 호출이 가능하다. 하지만 이니시스 결제 콜백은 서버사이드에서 실행되며, web-gateway를 거치지않기때문에 fetch시 호스트가 누락된 경로가 생성된 것이었다.

최종적으로는 환경 변수에 apiGatewayUrl 값을 명시적으로 추가하고,

• 이니시스(서버) 결제 시 → API_GATEWAY_URL 사용 (호스트 포함)
• 토스페이먼츠(클라이언트) 결제 시 → PAYMENT_PROXY_PATH 사용 (path만 사용)

으로 처리하여 문제를 해결했다.

---

✅ 정리하며

이번 이슈를 통해 fetch 호출 시 현재 코드가 서버사이드인지 클라이언트사이드인지 명확히 구분하는 습관의 중요성을 다시금 깨달았다.

특히 API 통신에서 환경 변수 처리 방식은 사이드에 따라 전혀 다르게 작동할 수 있으므로,환경변수(serverRuntimeConfig, process.env, publicRuntimeConfig)별 각각의 쓰임새를 잘 이해하고 적절히 사용해야 한다고 느꼈다.