Webpay Plus de Transbank: guía de implementación con IA paso a paso

Webpay Plus, el servicio de Transbank con el que el comprador escribe los datos de su tarjeta en Webpay y no en tu tienda, se puede implementar con ayuda de una IA y probar gratis antes de cobrar el primer peso. Lo comprobamos el 30 de octubre de 2026: en ocho pedidos a un solo asistente, Claude Code con Opus 5.5, armamos una tienda de ejemplo con catálogo, carro y checkout, y la sometimos a cinco pruebas automáticas en el ambiente de integración de Transbank, nunca en producción ni con una tarjeta real. La IA escribió una integración correcta, pero también afirmó algo que no había hecho, y solo se notó porque una prueba falló. Si en Chile te toca poner pagos en línea en una tienda online, como desarrollador independiente, en el equipo de TI de una pyme o a cargo del producto, esta guía de implementación de Webpay Plus con IA te cuenta qué pedirle, qué revisar y cómo comprobar, tú solo, que cobra bien antes de cobrar de verdad.

El resultado: una tienda con Webpay Plus, de punta a punta

La tienda de ejemplo se llama Tienda Pudú y está hecha con Node.js, Express y una base SQLite. Tiene catálogo, carro, checkout, página del pedido, comprobante y una página de «Pedidos» con el estado de cada compra. En la compra que mostramos, una taza de $15.990 y un patito que suman $22.980, pagados con la tarjeta VISA de prueba, el comprobante dijo «Tu pago fue aprobado», con la orden de compra, los últimos cuatro dígitos de la tarjeta, el código de autorización y el total.

La forma de trabajar fue siempre la misma, y es lo que vale la pena copiar: el pedido exacto a la IA, lo que respondió, qué se revisa en lo que entrega y cómo se comprueba que quedó bien. Una sola tienda y un solo asistente, de principio a fin.

Paso 1: qué necesitas, del SDK de Transbank a las tarjetas de prueba

Lo primero es no dejar que la IA adivine la versión. Según npm, el SDK oficial vigente de Transbank para Node.js es el 6.1.1, publicado el 9 de diciembre de 2025: pide Node 18 o más y depende solo de axios. Importa porque, según su registro de cambios, la versión 6.0.0 eliminó el constructor por defecto y varios métodos configureFor… de Webpay Plus, y el SDK dejó de apuntar por defecto al ambiente de integración. Hoy trae buildForIntegration y buildForProduction. El proyecto de ejemplo oficial de Node.js, en cambio, todavía usa WebpayPlus.configureForTesting() y fija la versión 5.0.0, así que copiarlo tal cual te deja en una versión anterior.

Lo demás lo entrega Transbank Developers sin costo. El ambiente de integración es de acceso libre y sus credenciales son públicas: un código de comercio de Webpay Plus y una llave secreta igual para todos los códigos. Para pagar, la tarjeta VISA de prueba genera transacciones aprobadas y la MASTERCARD, rechazadas; en el banco de prueba se usan el RUT 11.111.111-1 y la clave 123. Y una regla que vale desde el primer día: Transbank recomienda no dejar el código de comercio ni la llave en tu código, sino en variables de entorno.

Paso 2: cómo viaja un pago con Webpay Plus, en cuatro llamadas

Antes de pedirle nada a la IA conviene entender el viaje, porque es lo que vas a revisar. Primero, tu tienda crea la transacción con un POST, con la orden de compra, la sesión, el monto y la dirección de vuelta, y recibe un token y la dirección del formulario. Segundo, manda al comprador a ese formulario por POST, con el token en la variable tokenws; desde ahí, dice la documentación, la comunicación es entre Webpay y el tarjetahabiente, sin que intervenga el comercio. Tercero, Webpay devuelve al comprador a tu tienda con tokenws. Cuarto, tu tienda confirma la transacción con un commit, un PUT, y recién ahí obtiene el resultado. Sin ese último paso no hay venta, aunque el banco haya aprobado.

Pasos 3 y 4: la tienda, la transacción y la vuelta desde Webpay

El primer pedido a la IA fue solo la tienda: cinco productos, el total calculado en el servidor y nunca en el navegador, las compras guardadas en SQLite y, por ahora, sin pago. El segundo agregó Webpay Plus con una instrucción precisa: el SDK transbank-sdk en su versión 6.1.1, la documentación oficial, las llaves en el archivo .env y el comprador enviado a Webpay con un formulario POST que lleve token_ws.

En esta etapa la IA trabajaba sin terminal, y lo dijo: la integración quedó escrita, pero no la pudo probar. También avisó de lo que todavía faltaba: sin la vuelta, después de pagar en Webpay el comprador llegaría a una página 404 y la compra seguiría «Pendiente de pago».

La vuelta fue el tercer pedido, y aquí la documentación tiene un punto que confunde. En una misma frase dice que a la dirección de vuelta siempre se llega por POST y que, desde la versión 1.1 de la API, la redirección es por GET; además, describe cuatro flujos de vuelta, cada uno con datos distintos. Por eso le pedimos aceptar GET y POST, confirmar con commit de inmediato si llega token_ws y mostrar un comprobante. La respuesta separó los casos: si hay token, confirma; si el comprador anuló, consulta el estado sin confirmar; si se acabó el tiempo, cierra el intento. Y por su cuenta señaló lo que faltaba: si el commit falla por un corte de red, el intento queda como fallido y no se vuelve a revisar.

Paso 5: qué revisar en el código que te entrega la IA

El cuarto pedido fue una lista de siete controles, con una instrucción que conviene copiar: que agregue lo que falte y diga qué ya estaba. El principal viene de Transbank: un pago está aprobado solo si response_code es exactamente 0 y status es exactamente AUTHORIZED. La documentación agrega otro: el comercio debe verificar que el monto y la orden de compra que informa Transbank coincidan con los que envió al comienzo. También hay que revisar la anulación, el tiempo agotado, que los errores no tumben la tienda y que quede un registro de cada respuesta.

La respuesta fue útil: los puntos 1 a 5 ya estaban, agregó el registro y la página «Pedidos», y aclaró que revisó el código a mano, sin ejecutarlo, porque seguía sin terminal. También advirtió un riesgo: esa página queda pública, cualquiera que la abra ve los códigos de cada compra y, con esos enlaces, llega al nombre, el correo y el comprobante del comprador. Hay que protegerla con un inicio de sesión de administrador.

Paso 6: las pruebas con Playwright que escribe y corre la IA

Esta es la parte que responde la pregunta de la guía. En el quinto pedido le dimos a la IA una terminal limitada a npm, npx, node y sqlite3, y le pedimos escribir y correr pruebas con Playwright: cada una hace la compra completa como una persona y, al final, revisa el estado en SQLite y lo que quedó en el registro. Si alguna falla, primero el diagnóstico y después los cambios. La del tiempo agotado, que dura más de diez minutos, la corrimos nosotros. Las otras cuatro pasaron dos veces, y en la última ejecución tomaron 46 segundos en total.

Las cinco cuentan lo que de verdad importa antes de cobrar. La aprobada paga con la VISA y termina con la compra pagada en SQLite y response_code 0. La rechazada termina con el aviso de que no se hizo ningún cargo y de que se puede intentar de nuevo. En la anulada, el comprador anula en Webpay: la tienda avisa que no hubo cargo y la compra sigue «Pendiente de pago». La del tiempo agotado confirma lo que dice la documentación, 10 minutos en integración y 4 en producción: a los 9,97 minutos, Webpay devolvió al comprador solo con la orden y la sesión, sin token, y la tienda avisó que se acabó el tiempo y que no hubo cargo.

La quinta es la que más enseña. El comprador paga, el banco aprueba y cierra la pestaña antes de volver a la tienda. Como la vuelta no llegó, nadie confirmó el pago. Al reabrir esa dirección un minuto después, el commit tardío devolvió un error 422 con el estado aborted, y la tienda dijo «No pudimos confirmar tu pago con Webpay». En SQLite, la transacción quedó solo como creada.

El diagnóstico con el trace: la falla era de Webpay de integración

La primera vez que corrimos la prueba del tiempo agotado, falló a los 22 segundos, esperando ver el monto en Webpay. Se lo contamos a la IA en el sexto pedido, con una condición: primero el diagnóstico, sin cambiar nada todavía. Leyó el trace de Playwright y encontró unos 20 segundos de espera de esa verificación y una página de error del propio Webpay, en inglés. Su conclusión: la causa estaba dentro de Webpay de integración, no en la tienda ni en la prueba. La API había respondido «Transacción sin token» y, según el trace, la petición cayó en otro servidor de Transbank que no conocía esa sesión. Propuso dos cambios, sin aplicarlos: avisar con claridad cuando la falla es de Webpay y reintentar solo la entrada a Webpay. Es la lectura de la IA sobre el trace, no una explicación de Transbank, pero es lo que le pides a una prueba: saber dónde está el problema antes de tocar tu código.

Cuando la IA se equivoca: lo notamos porque otra prueba falló

Le pedimos aplicar las dos propuestas, y en su respuesta aseguró que la prueba «reconoce cuándo la falla es de Webpay». Las pruebas seguían pasando, así que nada obligaba a dudar. Pero esa revisión solo existía en dos momentos: después de apretar «Pagar con Webpay Plus» y después de apretar «Pagar» en Webpay. En la ejecución siguiente falló la prueba de la anulación, con un error de dirección y sin el mensaje claro prometido: la prueba seguía en Webpay.

Se lo dijimos en el octavo pedido. La IA encontró que era la misma falla de Webpay de integración, esta vez al anular, y admitió que su afirmación anterior «era más amplia que lo que había implementado». Reemplazó las dos verificaciones por un mecanismo único, y las cuatro pruebas rápidas volvieron a pasar contra Webpay, en el ambiente de integración, en 45,9 segundos. La del tiempo agotado, ya con la corrección, pasó en 10,1 minutos.

Paso 7: para cobrar de verdad, validación, llave de producción y tarifas

Para vender hay que salir del ambiente gratis, y Transbank lo divide en tres pasos. Completas el formulario de afiliación en su portal público, lo firmas digitalmente y recibes tu código de comercio por correo. Luego validas tu integración con el formulario de Transbank Developers. Al terminar la validación, te asignan la llave secreta de producción. Según sus preguntas frecuentes, si el comercio está validado y la documentación está correcta, el paso a producción toma 24 horas, y hay que hacer una prueba en producción para cerrar el proceso.

¿Cuánto cobra Transbank? Según su página de tarifas, los comercios nuevos desde el 1 de septiembre de 2026 pagan 2,29 % con crédito y 1,49 % con débito o prepago, sin IVA. Hicimos la cuenta con la taza de $15.990 y el IVA de 19 %: $435,74 de comisión si pagan con crédito y $283,52 si pagan con débito o prepago.

Qué significa para ti: la IA escribe, pero la prueba decide

Nuestra lectura: con la versión exacta del SDK y la documentación oficial a la vista, la IA escribió una integración de Webpay Plus correcta; con una terminal acotada, la probó y diagnosticó las fallas; y aun así afirmó algo que no había hecho, y eso solo se notó probando. Por eso importa el orden: primero le das la versión y la documentación, después le pides pruebas que ella misma corra, y no das por cierto lo que dice hasta que una prueba lo muestre.

Si vas a integrar Webpay Plus, antes de pedir la validación de Transbank comprueba en el ambiente gratis cuatro cosas. La primera, que solo das por aprobada una compra con response_code 0 y AUTHORIZED, con el monto y la orden correctos. La segunda, qué ve el comprador cuando la tarjeta se rechaza, cuando anula y cuando se le acaba el tiempo. La tercera, qué pasa si cierra la pestaña o si el commit falla por un corte de red. Y la cuarta, que tu página de pedidos no quede abierta a cualquiera.

Webpay Plus con IA funciona, y probarlo no cuesta nada, porque el ambiente de integración es gratis. Lo que sale caro es cobrar sin probar. ¿Qué prueba harías primero en tu tienda con Webpay Plus? Cuéntanos en los comentarios: opina con libertad, siempre con respeto.