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. Eso es lo que mantiene tu alcance de PCI DSS en el rango manejable, y es la razón por la que no hay que construir el formulario a mano por “control” — ese control cuesta una certificación.

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

Casi todos los problemas serios no son de código: son de no haber decidido qué pasa cuando el pago sale bien y el sistema no se entera.

Cómo lo hacemos

Integramos Niubiz y Culqi en sistemas en producción, con la conciliación y la facturación resueltas — no solo el botón de pago. Te ayudamos a elegir la pasarela correcta para tu etapa y a construir la integración que aguanta el tráfico real.

Conocemos el camino completo: la integración de la pasarela, el cruce con tu contabilidad y el cierre que tiene que cuadrar. Si tu sistema necesita cobrar en serio —y que cada cobro termine facturado y conciliado—, hablemos.

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.