Integración de pagos en Next.js: flujo 3D Secure con iyzico y PayTR

Desde fuera, la integración de pagos parece una simple llamada a una API: envías los datos de la tarjeta, recibes una respuesta de "éxito" y guardas el pedido. En Turquía no funciona así. La verificación de la tarjeta ocurre en la propia página del banco, el usuario sale de tu sitio, vuelve, y el banco te devuelve el resultado mediante una solicitud POST. Pierdes el control justo en mitad del flujo, y por eso la integración es tan complicada.

En este artículo, primero explicaré cómo funciona realmente el flujo y después te mostraré qué código escribir y dónde en el App Router de Next.js. Por último, te presentaré una librería de código abierto que creé y que envuelve cuatro proveedores (iyzico, PayTR, ParamPOS, Akbank) bajo una sola interfaz. Pero primero necesitas entender el mecanismo, porque la librería no se salta el mecanismo, solo elimina el código repetitivo.

Hay dos flujos distintos: 2D y 3D Secure

Pago 2D (directo): los datos de la tarjeta van de tu servidor al proveedor y la respuesta vuelve al instante. Una solicitud, una respuesta. Sencillo, pero en Turquía el 3D Secure es prácticamente obligatorio para los pagos con tarjeta, y algunos proveedores ni siquiera ofrecen 2D.

3D Secure: tres pasos, con el navegador justo en medio.

Dos detalles del tercer paso son la razón por la que la mayoría de las integraciones fallan al primer intento:

Y en segundo lugar: que la verificación 3DS sea correcta no significa que el pago se haya capturado. Después de que la verificación devuelva un resultado satisfactorio, debes hacer una llamada de completar o capturar (capture). Las integraciones que se saltan este paso parecerán "funcionar" en el sandbox de pruebas, pero en producción no cobrarán nada de dinero real.

Capturar el callback en el App Router de Next.js

El callback debe ser un Route Handler. No una página, porque recibe una solicitud POST.

import { NextRequest, NextResponse } from "next/server";
 
export async function POST(req: NextRequest) {
	// The provider sends form-encoded data; req.json() won't work here
	const form = await req.formData();
	const data = Object.fromEntries(form.entries()) as Record<string, string>;
 
	// ... complete payment, update order ...
 
	// Redirect user to a result page with 303:
	// This is the correct way to transition from POST to GET.
	return NextResponse.redirect(new URL("/siparis/tamam", req.url), 303);
}

El detalle del 303 See Other es crucial: la redirección 307 por defecto conserva el método, lo que significaría que el usuario llegaría a la página de resultado también con una solicitud POST, y al recargar la página el navegador mostraría el aviso de "confirmar reenvío del formulario". El 303 convierte la solicitud en un GET.

Nunca confíes en el cliente

Este es el error más caro en una integración de pagos, y también el más común.

// WRONG — the user can manipulate the price
const { price, basketItems } = await req.json();
await payment.initThreeDSPayment({ price, basketItems, ... });
 
// CORRECT — the client only tells you what they are buying
const { cartId } = await req.json();
const cart = await db.cart.findUnique({ where: { id: cartId } });
const price = cart.items.reduce((t, i) => t + i.price * i.quantity, 0);

La misma lógica se aplica al callback: los datos devueltos pueden contener un ID de pedido y un importe, pero no los proceses sin compararlos antes con tus propios registros.

El problema de la doble entrada

Puede que el callback no llegue una sola vez. El usuario podría pulsar atrás, el proveedor podría reintentar tras un timeout o podría haber un fallo de red. Recibir el callback dos veces para el mismo pago es un escenario perfectamente normal.

En la práctica: al iniciar un pago, crea por tu parte un registro de pedido pending. En el callback, busca ese registro por su ID y actualiza su estado. No crees un registro nuevo desde cero dentro del callback.

Los proveedores hacen lo mismo de forma distinta

En Turquía, cada proveedor de pagos impone su propia API propietaria: nombres distintos, métodos de firma distintos, formatos de error distintos. Tampoco sus conjuntos de funciones son idénticos:

Esta tabla también muestra por qué escribir tu integración directamente contra el SDK de un proveedor es arriesgado: PayTR no tiene endpoint de cancelación y ParamPOS no tiene consulta de cuotas. Cuando necesitas cambiar de proveedor, algo que ocurre con frecuencia por las comisiones, los contratos o las caídas del servicio, acabas reescribiendo tu código de pagos desde cero.

Envolverlos tras una sola interfaz

Escribí este código repetitivo una vez y lo publiqué como código abierto: better-payment, un paquete con licencia MIT escrito en TypeScript que unifica cuatro proveedores bajo la misma interfaz.

npm install better-payment

1. Crea la instancia de forma perezosa (lazy)

import { BetterPayment, ProviderType } from "better-payment";
 
let instance: BetterPayment | null = null;
 
export function getBetterPayment(): BetterPayment {
	if (!instance) {
		instance = new BetterPayment({
			defaultProvider: ProviderType.IYZICO,
			providers: {
				iyzico: {
					enabled: true,
					config: {
						apiKey: process.env.IYZICO_API_KEY!,
						secretKey: process.env.IYZICO_SECRET_KEY!,
						baseUrl:
							process.env.IYZICO_BASE_URL ?? "https://sandbox-api.iyzipay.com",
					},
				},
			},
		});
	}
	return instance;
}

El motivo para no escribir new BetterPayment(...) a nivel de módulo es específico de Next.js: las variables de entorno pueden no estar disponibles durante la generación estática de páginas, lo que puede romper el build. Envolverlo en una función aplaza la ejecución hasta la primera llamada.

2. Una única ruta catch-all

La librería trae su propio manejador HTTP; no necesitas escribir cada endpoint a mano.

import { NextRequest, NextResponse } from "next/server";
import type { BetterPaymentRequest } from "better-payment";
import { getBetterPayment } from "@/lib/payment";
 
async function handler(req: NextRequest) {
	const contentType = req.headers.get("content-type") ?? "";
	let body: unknown;
 
	if (req.method !== "GET" && req.method !== "HEAD") {
		if (contentType.includes("application/json")) {
			body = await req.json().catch(() => undefined);
		} else if (contentType.includes("application/x-www-form-urlencoded")) {
			const fd = await req.formData();
			const obj: Record<string, string> = {};
			fd.forEach((v, k) => {
				obj[k] = v as string;
			});
			body = obj;
		}
	}
 
	const request: BetterPaymentRequest = {
		method: req.method,
		url: req.url,
		headers: Object.fromEntries(req.headers.entries()),
		body,
	};
 
	const res = await getBetterPayment().handler.handle(request);
	return NextResponse.json(res.body, { status: res.status, headers: res.headers });
}
 
export const GET = handler;
export const POST = handler;

Maneja ambos tipos de contenido por el detalle del callback mencionado antes: las solicitudes de pago llegan como JSON, mientras que los retornos del proveedor llegan codificados como formulario.

Este único archivo expone los siguientes endpoints:

POST /api/pay/:provider/payment
POST /api/pay/:provider/payment/init-3ds
POST /api/pay/:provider/payment/complete-3ds
POST /api/pay/:provider/callback
POST /api/pay/:provider/refund
POST /api/pay/:provider/cancel
POST /api/pay/:provider/bin-check
POST /api/pay/:provider/installment
GET  /api/pay/health

3. Inicializa y completa el 3DS

const payment = getBetterPayment();
 
// Initialization — render the returned htmlContent to the browser
const init = await payment.initThreeDSPayment({
	price: "100.00",
	paidPrice: "100.00",
	currency: "TRY",
	callbackUrl: `${origin}/api/pay/iyzico/callback`,
	buyer: {
		/* ... */
	},
	basketItems: [
		/* ... */
	],
});
 
// Inside the callback — complete the payment
const done = await payment.completeThreeDSPayment({
	paymentId: data.paymentId,
	conversationId: data.conversationId,
});

Cuando quieras cambiar de proveedor, la llamada sigue siendo exactamente la misma; solo especificas el destino:

await payment.use("paytr").refund({ paymentId, price: "50.00", currency: "TRY", ip });

Antes de salir a producción

El último punto es un arma de doble filo: necesitas monitorizar el flujo de pagos, pero los números de tarjeta, los CVC y las fechas de caducidad no deben escribirse bajo ningún concepto en tus logs.

Conclusión

La dificultad de la integración de pagos no es la API en sí; es que el usuario sale de tu app y vuelve a mitad del flujo. Una vez que lo configuras correctamente, no tienes que volver a escribirlo, y por eso publiqué better-payment como código abierto. Tiene licencia MIT; úsalo libremente en tus propios proyectos.