Cómo integrar Niubiz en tu propio sistema

Niubiz —la ex VisaNet— es la procesadora de tarjetas más grande del Perú, y por eso termina siendo la pasarela obligada de casi cualquier empresa mediana o grande. También es, con diferencia, la más laboriosa de integrar: donde Culqi te pide una llave y un formulario, Niubiz te pide tres tokens encadenados y un backend que sepa qué hacer cuando algo se corta a mitad. Esta es la guía de lo que de verdad cuesta trabajo — escrita desde haberla puesto en producción, no desde leer el manual.

¿Cuándo conviene Niubiz y cuándo no?

Niubiz conviene cuando el volumen justifica negociar la tasa, cuando necesitas la mejor aprobación con tarjetas peruanas o cuando el antifraude importa de verdad. Si estás validando un producto y lo que necesitas es cobrar la semana que viene, Culqi te va a costar menos trabajo — y decirlo es parte de dar un buen consejo.

La decisión no es técnica, es de etapa. Niubiz procesa la mayoría de transacciones con tarjeta del país y su tasa es negociable a volumen: por encima de cierto nivel de facturación, la diferencia contra una pasarela de tarifa plana deja de ser trivial. A cambio, la integración es más larga y el proceso comercial de afiliación también. Si tu operación todavía no tiene ese volumen, la cuenta rara vez cierra a favor.

El flujo real: tres tokens, no uno

Cobrar con Niubiz encadena tres piezas: security token (autentica tu comercio), session token (autoriza esa sesión de pago concreta) y transaction token (lo devuelve el formulario cuando el cliente ingresa la tarjeta). Tu backend canjea el tercero por la autorización final.

En la práctica son dos APIs del lado servidor —una de sesión y otra de autorización— más el script de checkout que Niubiz sirve para renderizar el formulario en el navegador. Los endpoints y sus versiones cambian, así que el portal de desarrolladores es la única fuente que conviene tratar como autoridad; lo que no cambia es la forma del baile.

Lo importante de esa forma: la tarjeta nunca pasa por tu servidor. El formulario es de Niubiz y lo que vuelve a tu backend es un token, no un PAN. Esa frontera es la que decide cuánto te va a costar cumplir PCI DSS — y no de forma gradual. Traducido a esta guía: construir el formulario a mano por “control” es la decisión más cara que puedes tomar el primer día.

La trampa #1: el cliente ya pagó y tu sistema no se enteró

Entre que el formulario devuelve el transaction token y tu backend recibe la respuesta de autorización, hay una ventana donde todo puede fallar: un timeout, un deploy, un usuario que cierra la pestaña. El cargo puede existir en Niubiz y no en tu base. Esa ventana no se elimina — se diseña.

Es el problema serio de cualquier pasarela y el que más plata cuesta cuando no se previó. La defensa tiene tres piezas y ninguna es opcional:

Registra la intención antes de cobrar. Tu pedido debe existir en tu base, en estado pendiente, antes de que el cliente vea el formulario. Si el cargo aparece después y no encuentra pedido, no tienes contra qué conciliarlo.

Haz la autorización idempotente. Si el mismo transaction token llega dos veces —reintento, doble clic, callback duplicado— el segundo intento tiene que devolver el resultado del primero, no cobrar de nuevo.

Concilia contra la fuente de verdad. Un proceso que cruza periódicamente lo que dice Niubiz contra lo que dice tu base y levanta las diferencias. En el sistema de caja de una universidad nacional que construimos, ese cruce es lo que permite cerrar el día sin que nadie revise transacción por transacción.

La trampa #2: el número de pedido es único de verdad

El purchaseNumber identifica la compra ante Niubiz y no se puede reutilizar. Si tu sistema lo genera a partir de algo que se repite —el número de pedido tras un reintento, por ejemplo— vas a chocar con rechazos que parecen aleatorios y no lo son.

Es de los errores que más tiempo hacen perder porque el síntoma engaña: la integración “funciona” en pruebas y empieza a fallar con tráfico real, justo cuando hay reintentos. La regla práctica: un identificador nuevo por cada intento de cobro, guardado en tu base junto al pedido al que pertenece, para que un pedido pueda tener varios intentos y cada intento su propio rastro.

La trampa #3: devolver no es simétrico a cobrar

Los equipos asumen que si cobraron por API, devuelven por API. Con Niubiz el flujo de devoluciones tiene su propio camino —incluida la gestión desde el portal de comercio— y conviene confirmarlo con tu ejecutivo antes de prometer un botón de “anular” en tu panel.

No es un detalle menor: si tu producto promete devoluciones self-service y el flujo real pasa por una gestión distinta, acabas de crear trabajo manual para el área de operaciones. Súmale que las controversias y contracargos tienen su propio proceso — Niubiz publica un servicio específico para gestionarlos. Definir esto en el alcance, y no en la semana de salida a producción, es la diferencia entre un lanzamiento tranquilo y uno que no.

Sandbox: úsalo, pero no le creas del todo

Niubiz ofrece ambiente de pruebas con credenciales y tarjetas de prueba. Sirve para validar el flujo completo, pero el comportamiento del antifraude y los tiempos reales solo se ven en producción — así que reserva presupuesto para una etapa de pruebas con montos mínimos.

El patrón que nos funciona: cerrar el flujo entero en sandbox, salir a producción con un cobro real de monto mínimo, verificar que la conciliación cuadra de punta a punta —incluida la factura electrónica ante SUNAT si aplica— y recién entonces abrir el cobro al público. Es un día más de trabajo que evita una semana de conciliación manual.

Errores comunes al integrar Niubiz

El patrón se repite: el pago sale bien y el sistema no se entera. Todo lo que sigue son formas de cerrar esa ventana antes de que la cierre un cliente reclamando.

Cómo lo hacemos

El botón de pago es la parte corta. Lo que construimos es lo que va detrás: el cuadre que cierra el día, la factura que sale sola y el rastro que te deja defender un contracargo seis meses después.

Si tu volumen ya justifica Niubiz, el trabajo real empieza donde termina la autorización. Hacemos esa parte en sistemas donde el cierre diario no admite descuadres — hablemos antes de que la arquitectura quede fijada.

En resumen

Niubiz es la pasarela de las empresas con volumen en el Perú, y su precio es una integración más laboriosa: tres tokens encadenados, dos APIs en tu backend y un formulario que —afortunadamente— evita que la tarjeta toque tus servidores. Lo que decide si el proyecto sale bien no es el código del cobro, sino haber diseñado la ventana entre que el cliente paga y tu sistema se entera: intención registrada antes, autorización idempotente, identificador único por intento y una conciliación que cruce contra la fuente de verdad. Resuelto eso, cobrar deja de dar miedo.