Pasarelas de Pago en Perú: Integración con Niubiz, Culqi y Mercado Pago en Next.js

El éxito de una tienda online o plataforma SaaS en el mercado peruano depende en gran medida de ofrecer métodos de pago familiares, confiables y con baja tasa de fricción. En este artículo analizamos la integración técnica de Niubiz, Culqi y Mercado Pago utilizando Next.js 15 y TypeScript.

El Panorama de los Pagos Digitales en Perú#

El ecosistema de pagos en el Perú ha evolucionado a pasos agigantados. Para lograr altas tasas de conversión en checkout, los clientes esperan poder pagar no solo con tarjetas de crédito y débito (Visa, Mastercard, Amex, Diners), sino también mediante billeteras digitales (Yape, Plin) y transferencias bancarias directas (PagoEfectivo).

A nivel técnico, cada pasarela de pago ofrece ventajas particulares:

• Niubiz (PagoWeb / CyberSource): Es la red de procesamiento de pagos más grande del Perú, ideal para empresas corporativas y transacciones con alta exigencia de aceptación bancaria.
• Culqi (del Grupo Credicorp): Diseñada específicamente para desarrolladores peruanos, con una API REST moderna, tokenización sencilla y soporte nativo para Yape mediante código de aprobación.
• Mercado Pago: Excelente experiencia de usuario, integración de split de pagos para marketplaces y soporte de múltiples métodos de pago en una sola integración (Checkout Pro / Checkout Bricks).

Comparativa Técnica para Desarrolladores#

Implementación de Tokenización y Cargo con Culqi en Next.js#

Para procesar pagos con tarjeta sin comprometer la seguridad ni almacenar datos sensibles (cumplimiento PCI-DSS), utilizamos el flujo de Tokenización en el cliente y Creación del cargo en el servidor.

1. Componente de Checkout en el Cliente (React)#

"use client";

import { useEffect, useState } from "react";

declare global {
  interface Window {
    Culqi: any;
    culqi: () => void;
  }
}

export default function CheckoutCulqi({ amount, orderId }: { amount: number; orderId: string }) {
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    // Cargar SDK oficial de Culqi
    const script = document.createElement("script");
    script.src = "https://checkout.culqi.com/js/v4";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  const handlePay = () => {
    if (!window.Culqi) return;

    window.Culqi.publicKey = process.env.NEXT_PUBLIC_CULQI_PUBLIC_KEY;
    window.Culqi.settings({
      title: "Brayan Developer Store",
      currency: "PEN",
      amount: amount * 100, // En céntimos
      order: orderId,
    });

    window.Culqi.options({
      lang: "es",
      installments: true,
      modal: true,
    });

    // Callback al generar el token
    window.culqi = async () => {
      if (window.Culqi.token) {
        const tokenId = window.Culqi.token.id;
        const email = window.Culqi.token.email;
        setLoading(true);

        const res = await fetch("/api/payments/culqi/charge", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ tokenId, email, amount, orderId }),
        });

        const result = await res.json();
        setLoading(false);

        if (result.success) {
          window.location.href = `/checkout/success?order=${orderId}`;
        } else {
          alert(`Error en el pago: ${result.message}`);
        }
      } else if (window.Culqi.error) {
        console.error("Error Culqi:", window.Culqi.error);
        alert(window.Culqi.error.user_message);
      }
    };

    window.Culqi.open();
  };

  return (
    <button
      onClick={handlePay}
      disabled={loading}
      className="w-full rounded-xl bg-emerald-600 px-6 py-4 font-semibold text-white shadow-lg transition-all hover:bg-emerald-500 disabled:opacity-50"
    >
      {loading ? "Procesando pago seguro..." : `Pagar S/ ${(amount).toFixed(2)}`}
    </button>
  );
}

2. Route Handler de Cargo en el Servidor (Next.js App Router)#

En el backend, ejecutamos el cobro contra la API privada de Culqi:

// src/app/api/payments/culqi/charge/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  try {
    const { tokenId, email, amount, orderId } = await req.json();

    const response = await fetch("https://api.culqi.com/v2/charges", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.CULQI_SECRET_KEY}`,
      },
      body: JSON.stringify({
        amount: Math.round(amount * 100),
        currency_code: "PEN",
        email: email,
        source_id: tokenId,
        description: `Pago Orden #${orderId}`,
        antifraud_details: {
          first_name: "Cliente",
          last_name: "Web",
          email: email,
          device_finger_print_id: "device-session-id",
        },
      }),
    });

    const chargeData = await response.json();

    if (!response.ok) {
      return NextResponse.json(
        { success: false, message: chargeData.user_message || "Error al procesar el cargo" },
        { status: 400 }
      );
    }

    // Registrar pago exitoso en base de datos y activar orden
    return NextResponse.json({ success: true, chargeId: chargeData.id });
  } catch (error) {
    console.error("Error en servidor al procesar cargo:", error);
    return NextResponse.json({ success: false, message: "Error interno" }, { status: 500 });
  }
}

Estrategias de Prevención de Fraude y Webhooks Seguros#

Para garantizar que ningún pedido se procese sin validación real:

1. Confirmación Asíncrona vía Webhooks: Nunca confíes únicamente en la respuesta del navegador del usuario. El servidor debe escuchar las notificaciones automáticas de la pasarela para marcar una orden como PAGADA.
2. Validación de Firmas: Verifica las firmas criptográficas de los headers en cada webhook entrante para prevenir peticiones maliciosas de terceros.
3. Soporte de 3D Secure (3DS 2.0): Obligatorio para reducir contracargos en tarjetas de alto riesgo.

¿Deseas Integrar Pasarelas de Pago en tu E-commerce o SaaS?#

Una pasarela de pagos bien integrada incrementa tu tasa de conversión, protege tu negocio contra fraudes y simplifica el flujo de compra para tus usuarios.

Si necesitas ayuda profesional para integrar Niubiz, Culqi, Mercado Pago o Stripe en tu aplicación web o móvil, ponte en contacto con nosotros o explora nuestros servicios de desarrollo e-commerce.