Overview
Framework adapters for Next.js, React Router, Express, Fastify, Hono, Elysia, Node.js and edge runtimes.
Each adapter is a separate import and has no dependencies, so you only load the one you use.
| Framework | Import | Function |
|---|---|---|
| Next.js | better-payment/next | toNextJsHandler |
| React Router | better-payment/react-router | toReactRouterHandler |
| Express | better-payment/express | toExpressHandler |
| Fastify | better-payment/fastify | toFastifyPlugin |
| Hono | better-payment/hono | toHonoHandler |
| Elysia | better-payment/elysia | toElysiaHandler |
| Node.js | better-payment/express | toNodeHandler |
| Cloudflare Workers, Deno, Bun | better-payment | toFetchHandler |
All adapters:
- pass JSON and form-urlencoded bodies (the bank callbacks) to the handler
- send PayTR's
OKas plain text - keep the
Locationheader of redirects (callbackRedirect)
Register them under the handler's basePath (default /api/pay). For a framework that is not listed, see other frameworks.
Express
import express from 'express';
import { toExpressHandler } from 'better-payment/express';
import { payment } from './payment';
const app = express();
app.all('/api/pay/*path', toExpressHandler(payment)); // Express 4: '/api/pay/*'You don't need express.json() or express.urlencoded() for the payment routes, because the adapter reads the raw body. If a body parser runs first, its result is used. Unexpected errors are passed to next(error).
Fastify
import Fastify from 'fastify';
import { toFastifyPlugin } from 'better-payment/fastify';
const app = Fastify();
await app.register(toFastifyPlugin(payment), { prefix: '/api/pay' });Fastify rejects application/x-www-form-urlencoded bodies by default (415), but iyzico, Param, Akbank and PayTR post their callbacks in that format. The plugin accepts it for its own routes only, so your other routes keep Fastify's defaults.
NestJS
import { All, Controller, Req, Res } from '@nestjs/common';
import { toNestHandler } from 'better-payment/nestjs';
import { getPayment } from './payment';
@Controller('api/pay')
export class PaymentController {
// One handler works on both the Express and the Fastify platform
private readonly handle = toNestHandler(getPayment);
@All('*')
pay(@Req() req: unknown, @Res() res: unknown): Promise<void> {
return this.handle(req, res);
}
}better-payment/nestjs has no dependency on @nestjs/*: the adapter only reads the request and response objects Nest injects with @Req() and @Res(), and detects the platform from the response. On the Express platform it is the Express middleware (it reads the raw body, so the default body parser never breaks the form-urlencoded bank callbacks); on the Fastify platform it uses the body Fastify already parsed. Register the wildcard route under the handler's basePath (api/pay here). Because the adapter takes the handler as a function, lazy initialization works exactly like the other adapters.
Hono
import { Hono } from 'hono';
import { toHonoHandler } from 'better-payment/hono';
const app = new Hono();
app.all('/api/pay/*', toHonoHandler(payment));Hono runs on Node.js, Bun, Deno and Cloudflare Workers, like Better Payment.
Elysia
import { Elysia } from 'elysia';
import { toElysiaHandler } from 'better-payment/elysia';
const app = new Elysia();
app.all('/api/pay/*', toElysiaHandler(payment), { parse: 'none' });{ parse: 'none' } keeps the raw body for the handler: bank callbacks are form-urlencoded and their signatures are checked against the original fields. Without it, any hook that reads body (onTransform, derive, onBeforeHandle or a plugin) makes Elysia consume the request first. Elysia is built for Bun and also runs on Node.js.
React Router
Added in 0.8.0// app/routes/api.pay.$.ts
import { toReactRouterHandler } from 'better-payment/react-router';
import { getBetterPayment } from '~/lib/payment.server';
export const { loader, action } = toReactRouterHandler(getBetterPayment);A splat resource route (api.pay.$.ts matches everything under /api/pay) with no default export: GET requests go to loader, POST requests (bank callbacks included) to action. The same code works in Remix v2. With routes.ts config, register it as route('api/pay/*', 'routes/api.pay.$.ts').
Plain Node.js
import { createServer } from 'node:http';
import { toNodeHandler } from 'better-payment/express';
createServer(toNodeHandler(payment)).listen(3000);Lazy initialization
Every adapter also accepts a function that returns the payment object (or its handler). The function is called on each request, so you can create the instance on first use:
const createPayment = () => betterPayment({ /* ... */ });
let instance: ReturnType<typeof createPayment> | undefined;
const getPayment = () => (instance ??= createPayment());
app.all('/api/pay/*path', toExpressHandler(getPayment));Request body size
Added in 0.8.1The Express, Node.js and fetch-based adapters read at most 1 MiB of a request body and answer 413 for larger ones. Bank callbacks are a few kB. Change the limit with maxBodySize (in bytes) on toExpressHandler, toNodeHandler or toFetchHandler:
app.all('/api/pay/*path', toExpressHandler(payment, { maxBodySize: 64 * 1024 }));Fastify applies its own bodyLimit (1 MiB by default).