Integración Transbank Webpay Chile: API REST, OneClick y marketplace

Transbank expone hoy un set de APIs REST modernas (Webpay Plus REST, Onepay, OneClick Mall, Webpay Mall) que reemplazaron al antiguo KCC SOAP. La integración típica con un e-commerce sigue cinco pasos. Primero, dar de alta el comercio en el portal de Transbank Developers y obtener las credenciales: API Key y Commerce Code para el ambiente de integración (sandbox) y luego para producción. Segundo, instalar el SDK oficial: existen librerías mantenidas por Transbank para PHP, Node.js, Java, .NET, Ruby y Python que encapsulan la autenticación, los headers, el manejo de tokens y la firma de las llamadas. Tercero, construir el flujo de pago: en el checkout, el backend del comercio llama al endpoint create de Webpay Plus con monto, orden de compra, sesión y return URL, recibe un token y una URL del formulario de Transbank, y redirige al cliente a esa URL. El cliente ingresa los datos de su tarjeta directamente en el formulario de Transbank (los datos sensibles nunca pasan por tu servidor, lo que reduce drásticamente el alcance PCI-DSS). Cuarto, el cliente vuelve al return URL con el token, el backend llama al endpoint commit para confirmar la transacción y recibe el resultado: autorizado o rechazado, con monto, código de autorización, tipo de tarjeta y número de cuotas. Quinto, el comercio genera la boleta o factura electrónica vía SII y muestra la confirmación al cliente. En Blackend, además de codificar el flujo feliz, blindamos los flujos de error: pagos pendientes que quedan en estado intermedio, doble click del usuario, timeouts en la red, retornos manipulados y reintentos. Todo encolado con idempotencia, lo que es indispensable para evitar cobros duplicados o ventas perdidas en escenarios reales.

En el mercado chileno, una integración custom de Webpay Plus REST en un e-commerce propio o headless parte desde $3.500.000 CLP y llega a $9.000.000 CLP según complejidad. El piso baja a $2.500.000 CLP cuando se trata solo de Webpay Plus en un checkout estándar con un flujo de pago lineal, y sube cuando entran en juego: Webpay Mall con múltiples comercios hijos (marketplace), OneClick con inscripción de tarjeta para suscripciones, Onepay para pagos móviles con QR, captura diferida (autorizar hoy, capturar al despachar), refunds parciales, conciliación automatizada con boleta electrónica SII e integración a ERP. Un proyecto marketplace completo (Webpay Mall + OneClick + comisiones automáticas a vendedores + dashboard de transacciones por comercio) se ubica entre $12.000.000 y $25.000.000 CLP. Sobre el build se suma soporte mensual de $400.000 a $1.200.000 CLP que cubre monitoreo de la tasa de aprobación, alertas por caídas de Webpay, conciliación diaria contra el cierre de Transbank, adaptación a cambios de la API y bolsa de horas evolutivas. A esto hay que sumar lo que cobra Transbank al comercio: la afiliación es gratuita en los planes estándar y la comisión por transacción depende del rubro y volumen (usualmente entre 1,79% y 2,95% para débito y entre 2,49% y 3,49% para crédito), comisión que el comercio negocia directamente con Transbank, no con nosotros.

Son productos distintos del mismo ecosistema Transbank pensados para casos de uso diferentes. Webpay Plus es el clásico checkout web: el cliente paga con tarjeta de crédito o débito en cualquier banco chileno, ingresa los datos en el formulario hospedado de Transbank y vuelve al comercio con la confirmación. Es el producto base de todo e-commerce chileno y aplica para compras puntuales. Onepay nació como producto móvil con QR: el cliente escanea un código desde la app de Onepay o de su banco y autoriza el pago sin tipear datos de tarjeta. Es útil para checkouts mobile-first, pagos en punto de venta físico con QR dinámico y flujos donde se prioriza la rapidez. OneClick es el producto de tokenización para compras recurrentes y suscripciones: el cliente inscribe su tarjeta una sola vez (un Webpay Plus de $0 o $50 reservado), Transbank devuelve un token que el comercio guarda asociado al usuario, y a futuro el comercio puede cobrar a esa tarjeta sin que el cliente vuelva a ingresar datos. Es la pieza clave para SaaS B2B, plataformas de membresía, gimnasios, colegios, suscripciones de delivery y todo modelo recurrente. Existe también OneClick Mall, que combina tokenización con la lógica multi-comercio de Webpay Mall para marketplaces con suscripciones por vendedor. La elección no es excluyente: la mayoría de proyectos serios combinan Webpay Plus para checkouts esporádicos y OneClick para clientes que se quieren retener. Onepay se suma cuando hay foco en mobile o en punto de venta físico.

Sí, y es uno de los casos de uso donde la integración custom marca la mayor diferencia respecto a un plugin genérico. El flujo de OneClick Mall (la versión vigente del producto, anterior OneClick original fue deprecada) tiene dos partes. Primera parte: inscripción. El cliente se registra en tu plataforma y, cuando quiere agregar un método de pago, lo enviamos al formulario de OneClick Mall con un identificador único de usuario (username) y un email. El cliente ingresa los datos de su tarjeta una sola vez, Transbank ejecuta una operación de inscripción (que puede incluir una autorización mínima de validación que se anula automáticamente) y devuelve un token único asociado a ese usuario más el comercio. Ese token se guarda en tu base de datos y nunca expira mientras la tarjeta esté vigente. Segunda parte: cobro recurrente. Cuando llega la fecha de facturación de la suscripción (mensual, anual, por consumo), tu sistema llama a la API de OneClick Mall con el token guardado, los datos del cobro (monto, comercio hijo si aplica, orden de compra) y Transbank ejecuta el cargo sin intervención del cliente. La respuesta es inmediata: autorizado o rechazado con código específico (sin cupo, tarjeta vencida, robada, bloqueada). El sistema de cobranza tiene que manejar este resultado: emitir boleta o factura en caso de éxito, reintento programado en caso de rechazos blandos, dunning automatizado con email/SMS para que el cliente actualice su tarjeta. En Blackend construimos toda esa máquina de estados: tokens vigentes, intentos fallidos, reintentos, suspensiones, re-activaciones, cambios de plan, prorrateos. Sin esa capa, OneClick es solo un cargador de tarjeta; con esa capa, es la columna vertebral de un SaaS chileno con churn bajo control.

Webpay y la boleta electrónica son dos sistemas independientes que el comercio chileno tiene la obligación legal de unir. Transbank procesa el pago y emite un comprobante interno (voucher) pero no emite documento tributario. El SII obliga a que toda venta a consumidor final tenga su boleta electrónica emitida y enviada al portal del SII, y toda venta entre empresas tenga su factura electrónica 33 o exenta 34. La integración correcta enlaza ambos flujos en cascada. Cuando Webpay responde con autorización exitosa en el commit, tu backend dispara la emisión del DTE correspondiente: boleta 39 si es venta a consumidor, factura 33 si el cliente es empresa con RUT (el frontend debe pedir el dato de "factura sí/no" antes del pago). El DTE se emite contra el proveedor que tengas: el módulo de facturación nativo de tu ERP (Defontana, Bsale, Manager, Softland) o un proveedor especializado como Haulmer, OpenFactura, Toctoc, Acepta o el módulo SII directo. El folio asignado, el track ID y el PDF/XML del DTE se asocian a la transacción Webpay original con el mismo correlation ID, lo que permite reconciliar después. En la página de éxito al cliente, mostramos tanto el código de autorización Transbank como el folio de la boleta o factura y el link de descarga del PDF. Si la emisión del DTE falla (folio agotado, certificado caducado, error del proveedor), no anulamos el pago Webpay: encolamos el documento pendiente y notificamos al equipo administrativo para resolver, porque revertir el cobro en frío es peor experiencia para el cliente. Detalles completos en nuestra página de integración SII boleta electrónica.

Sí, y es una decisión recomendable en la mayoría de los e-commerce chilenos. Webpay cubre todo el universo de tarjetas de crédito y débito chilenas (RedCompra), pero deja fuera varios segmentos importantes: clientes que prefieren transferencia bancaria desde la app de su banco (Khipu, Fintoc, Flow), clientes que pagan con saldo de Mercado Pago, clientes internacionales con tarjetas extranjeras (que Webpay puede rechazar por restricciones del comercio o el banco emisor) y clientes con tarjetas prepago que algunos bancos no enrolan en Webpay. La arquitectura recomendada es un checkout con orquestador de medios de pago: el cliente elige el método y el orquestador llama al SDK correspondiente con el mismo modelo de orden de compra. Cada pasarela tiene su flujo (Webpay con formulario hospedado, Mercado Pago con checkout pro o checkout bricks, Khipu con redirección al banco, Fintoc con PSD2 chileno) pero la lógica del comercio (creación de orden, manejo de éxito/rechazo, emisión de DTE, conciliación) se centraliza. En Blackend implementamos este patrón con un módulo de payment-orchestration agnóstico que abstrae las diferencias, lo que tiene tres beneficios: permite agregar o quitar pasarelas sin tocar el resto del sistema, da visibilidad consolidada de tasa de aprobación por proveedor (Webpay vs Mercado Pago vs Khipu) y permite hacer A/B testing del medio default. La regla práctica: en e-commerce B2C chileno, Webpay debería ser default por cobertura y conversión, pero ofrecer Khipu o Fintoc baja comisiones para el ticket alto y Mercado Pago abre el segmento sin tarjeta o con saldo guardado.

PCI-DSS es el estándar de seguridad para procesar datos de tarjetas de crédito y su cumplimiento es obligatorio para cualquier comercio que toque ese dato, sin importar el tamaño. La buena noticia con Webpay es que el modelo de integración Webpay Plus REST y OneClick Mall mantiene al comercio en SAQ-A o SAQ-A-EP, el nivel más bajo de exigencia, porque los datos sensibles de la tarjeta (número completo, CVV, fecha de vencimiento) jamás pasan por tu infraestructura. El cliente los ingresa directamente en el formulario hospedado de Transbank, en un dominio webpay.cl, y tu sistema solo ve el token y los últimos 4 dígitos. Esto es muy distinto a integraciones tipo Stripe Elements donde los datos pasan por iframe en tu dominio. Dicho esto, hay obligaciones que sí aplican y que no se pueden saltar. Primero, TLS 1.2 o superior en todo tráfico entre tu sistema y Transbank, sin excepciones. Segundo, las API Keys y Commerce Codes son secretos PCI: van en vault o KMS (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault), nunca en código ni en variables de entorno planas, con rotación documentada al menos anual. Tercero, los tokens de OneClick son datos sensibles bajo PCI: si bien no permiten ver el PAN, permiten cobrar a la tarjeta, así que tienen el mismo tratamiento que un secreto: cifrado en reposo, acceso auditado, no enviar por email ni Slack. Cuarto, logs sin almacenar datos sensibles: nunca el número de tarjeta, CVV ni fecha de vencimiento; sí los últimos 4, el código de autorización Transbank y el token de la operación. Quinto, separación estricta de ambientes: las credenciales de integración (sandbox) y producción son distintas y los repositorios y CI/CD no pueden mezclar. En clientes regulados (fintech, salud, retail grande) sumamos pen testing previo a producción y revisión de arquitectura PCI por un asesor externo. La regla de oro: si tu proveedor de integración propone "guardar la tarjeta" en una tabla propia, corre. Eso te saca de SAQ-A inmediatamente y dispara obligaciones de auditoría anual y certificación que cuestan más de 20 millones al año.

El tiempo total depende del alcance y del proceso de Transbank, no solo del código. Una integración Webpay Plus REST simple, en un e-commerce propio con backend ya montado, se construye en 2 a 3 semanas de desarrollo, pero hay que sumarle el proceso administrativo. Primero, el comercio debe afiliarse a Transbank si no lo está: papeleo, validación tributaria, definición del rubro y firma del contrato, lo que toma de 1 a 3 semanas dependiendo de la diligencia del equipo administrativo. Segundo, una vez con afiliación, se solicitan las credenciales de integración (sandbox), que llegan en horas. Tercero, desarrollo y pruebas en sandbox: 2 a 4 semanas según complejidad. Cuarto, certificación: para los productos básicos (Webpay Plus REST estándar) Transbank tiene un proceso de auto-certificación con casos de prueba documentados que el equipo de desarrollo ejecuta y reporta. Para productos más complejos (Webpay Mall, OneClick Mall, captura diferida con flujos especiales) hay revisión humana por parte de Transbank que puede tomar 1 a 2 semanas adicionales. Quinto, credenciales de producción y go-live: típicamente la misma semana que se completa la certificación. Sexto, monitoreo post-launch durante las primeras 2 semanas para ajustar parámetros de timeout, manejo de errores y tasa de aprobación. Un proyecto típico Webpay Plus + boleta SII + un par de medios alternativos toma 6 a 10 semanas calendario. Un proyecto marketplace completo con Webpay Mall + OneClick Mall + comisiones automáticas + conciliación se ubica entre 12 y 20 semanas. La mayor causa de demora suele estar en el lado del cliente: afiliación con Transbank en pausa, definición tardía del rubro contable, ausencia de proveedor de boleta electrónica decidido, falta de QA dedicada en el equipo del comercio.