🧭 How to Exclude a Route from Global Prefix & Versioning in NestJS

#nestjs #backend #api #express

In NestJS apps, it's common to use global route prefixes and versioning like /api/v1. But sometimes you need a public-facing endpoint — such as a payment gateway callback — that must live outside those constraints.

Here’s how to expose routes like /payment/callback without the global /api/v1 prefix.

🔧 Problem
You're using global prefixing and versioning like this:

main.ts:

app.setGlobalPrefix('api');
app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
});

✅ Resulting in routes like:

/api/v1/auth/login

/api/v1/user/profile

❌ But now you need /payment/callback to be exposed at:

http://localhost:3000/payment/callback

Instead of:

http://localhost:3000/api/v1/payment/callback

✅ Solution Overview
You need to do two things:

⛔ Exclude the route from the global prefix

⛔ Mark the route as version-neutral

Exclude the Route from Global Prefix Update main.ts:

import { RequestMethod } from '@nestjs/common';

app.setGlobalPrefix('api', {
  exclude: [{ path: 'payment/callback', method: RequestMethod.GET }],
});

This tells NestJS to ignore prefixing for GET /payment/callback

🚫 No leading slash in path (correct: payment/callback)

Mark Route as Version-Neutral Update your controller:

import { Controller, Get, Version, VERSION_NEUTRAL } from '@nestjs/common';

@Controller('payment')
export class PaymentController {
  @Get('callback')
  @Version(VERSION_NEUTRAL)
  callback() {
    return 'Payment callback hit!';
  }
}