Skip to content
Better Payment

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.

FrameworkImportFunction
Next.jsbetter-payment/nexttoNextJsHandler
React Routerbetter-payment/react-routertoReactRouterHandler
Expressbetter-payment/expresstoExpressHandler
Fastifybetter-payment/fastifytoFastifyPlugin
Honobetter-payment/honotoHonoHandler
Elysiabetter-payment/elysiatoElysiaHandler
Node.jsbetter-payment/expresstoNodeHandler
Cloudflare Workers, Deno, Bunbetter-paymenttoFetchHandler

All adapters:

  • pass JSON and form-urlencoded bodies (the bank callbacks) to the handler
  • send PayTR's OK as plain text
  • keep the Location header 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.1

The 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).