Transbank Developers: cómo integrar Webpay Plus paso a paso y resolver sus errores (2026)

Transbank Developers (transbankdevelopers.cl) es el portal oficial donde Transbank publica la documentación, los SDK, los plugins y las credenciales de prueba para integrar Webpay Plus y sus otros productos en tu sitio web. Para cobrar con Webpay Plus en tu tienda online se siguen 4 pasos: 1) haces tu afiliación en publico.transbank.cl y recibes tu código de comercio; 2) integras con un plugin o un SDK usando el ambiente de pruebas (código 597055555532 y tarjetas de prueba); 3) envías el formulario de validación con tus evidencias; y 4) Transbank te asigna tu llave secreta (API Key Secret) para pasar a producción y empezar a vender.

Abajo tienes los datos de prueba en una sola tabla, el código mínimo para crear y confirmar un pago, cómo pasar a producción y los errores que más se repiten. Si no programas y solo quieres cobrar, salta a cobrar con tarjeta sin integrar nada.

Fuente: Transbank Developers, Cómo empezar y Referencia API Webpay, revisados el 26-10-2026.

Qué es Transbank Developers y qué encuentras ahí

Es el sitio para quienes programan o integran pagos: no es donde contratas Webpay (eso se hace en publico.transbank.cl), sino donde aprendes a conectarlo a tu web. Puedes leer y descargar todo sin registrarte; si creas una cuenta de integrador accedes a herramientas extra, eLearning y la comunidad. Lo más útil:

• Documentación por producto: Webpay Plus (pago normal en tu tienda), Webpay Plus Mall (varias tiendas en un solo carro), Oneclick (tarjeta guardada para cobros con un clic), Transacción Completa (formulario propio, solo para comercios autorizados), Patpass (cargos recurrentes) y POS Integrado (máquinas conectadas a tu sistema de caja).
• Referencia API REST: cada endpoint, sus parámetros y respuestas.
• SDK oficiales para PHP, Java, .NET, Python, Node.js y Ruby, con proyectos de ejemplo que puedes probar en línea.
• Plugins para tiendas como WooCommerce, que no requieren escribir código.
• Credenciales y tarjetas de prueba, el estado de los sistemas y un Slack de la comunidad para preguntar.

Si todavía no sabes si te conviene Webpay Plus, cuánto cobra y cómo se contrata, parte por nuestra guía de Webpay Plus 2026.

Los 4 pasos para integrar Webpay Plus

1. Hazte cliente. Completa la afiliación en publico.transbank.cl, fírmala digitalmente y recibirás tu código de comercio por correo. Este trámite comercial puede ir en paralelo con la parte técnica.
2. Intégrate. Instala un plugin oficial o un SDK y haz todas las pruebas en el ambiente de integración con las credenciales públicas.
3. Valida. Transbank exige una validación antes de dejarte en producción: haces una serie de pruebas y envías las evidencias con el formulario de validación. Solo valida integraciones de comercios que ya tienen código de comercio productivo. Dudas a soporte@transbank.cl.
4. Vende. Al terminar la validación te asignan tu llave privada (Tbk-Api-Key-Secret). La configuras junto con tu código de comercio y quedas en producción.

Ejemplo: Carolina vende velas y jabones artesanales por Instagram y le pidió a un programador freelance que conecte Webpay a su web. Mientras ella firma la afiliación, él integra y prueba con las tarjetas de prueba. Cuando llega el código de comercio, envían la validación, reciben la llave y cambian dos datos en la configuración. No hay que rehacer la integración.

Plugin, SDK o API REST: cuál usar

Transbank recomienda usar plugins y SDK: ya traen las credenciales de prueba configuradas y se encargan de los detalles. Si tu integración todavía usa la antigua versión SOAP de Webpay, Transbank avisó que esa modalidad será deprecada y pide migrar a REST.

Cómo funciona un pago con Webpay Plus (create, redirect y commit)

Paso 1: crear la transacción

Tu backend llama a create con cuatro datos: la orden de compra (buy_order, única y de máximo 26 caracteres), un identificador de sesión (session_id, máximo 61), el monto y la URL de retorno (return_url, máximo 256). Webpay responde con un token y una url. Ejemplo con el SDK de Node.js en ambiente de pruebas:

const { WebpayPlus, Options, IntegrationCommerceCodes, IntegrationApiKeys, Environment } = require('transbank-sdk');

const tx = new WebpayPlus.Transaction(new Options(
  IntegrationCommerceCodes.WEBPAY_PLUS,  // 597055555532 en pruebas
  IntegrationApiKeys.WEBPAY,             // llave pública de integración
  Environment.Integration
));

// buy_order: único, máximo 26 caracteres, sin acentos
const createResponse = await tx.create('pedido-1043', 'sesion-1043', 25000, 'https://tutienda.cl/pago/retorno');
// createResponse.url y createResponse.token

Si usas la API directa, es un POST con los headers de autenticación:

POST https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions
Tbk-Api-Key-Id: 597055555532
Tbk-Api-Key-Secret: (llave de integración publicada en Transbank Developers)
Content-Type: application/json

{"buy_order": "pedido-1043", "session_id": "sesion-1043", "amount": 25000, "return_url": "https://tutienda.cl/pago/retorno"}

Paso 2: enviar al cliente al formulario de Webpay

Con la respuesta armas un formulario que envía el token por POST, en un campo llamado token_ws, a la url que te entregó Webpay:

<form method="post" action="URL_ENTREGADA_POR_WEBPAY">
  <input type="hidden" name="token_ws" value="TOKEN_ENTREGADO" />
  <input type="submit" value="Ir a pagar" />
</form>

Dos cuidados: el token vence en 5 minutos, así que créalo justo cuando el cliente aprieta «pagar»; y Transbank no recomienda abrir Webpay dentro de un iframe, porque el formulario puede no desplegarse.

Paso 3: confirmar el pago (commit)

Cuando el cliente termina, Webpay lo devuelve a tu return_url con el token_ws (por GET desde la versión 1.1 del API). Ahí llamas a commit. El pago está aprobado solo si response_code es exactamente 0 y status es exactamente AUTHORIZED.

// En tu return_url (GET en producción, API 1.1 o superior)
const token = req.query.token_ws || req.body.token_ws;
const r = await tx.commit(token);

if (r.response_code === 0 && r.status === 'AUTHORIZED') {
  // pago aprobado: marca el pedido como pagado y muestra el comprobante
} else {
  // pago rechazado: avisa al cliente y deja el pedido pendiente
}

La respuesta también trae los 4 últimos dígitos de la tarjeta, el código de autorización, las cuotas y el tipo de pago: VD (débito), VN (crédito normal), VC (cuotas), SI (3 cuotas sin interés), S2 (2 cuotas sin interés), NC (N cuotas sin interés) y VP (prepago).

Qué llega a tu return_url según lo que pasó

Para revisar un pago dudoso existe status(token), que funciona hasta 7 días después de creada la transacción. Los estados posibles son INITIALIZED, AUTHORIZED, REVERSED, FAILED, NULLIFIED, PARTIALLY_NULLIFIED y CAPTURED. Para devolver dinero se usa refund, que según el caso será una reversa o una anulación.

Tarjetas de prueba de Webpay

En todas sirve cualquier fecha de vencimiento futura. Si aparece la pantalla del banco, usa RUT 11.111.111-1 y clave 123. Prueba siempre al menos un pago aprobado, uno rechazado y uno anulado: son los casos que te pedirán en la validación.

Cómo pasar a producción

1. Confirma que ya tienes tu código de comercio productivo (sin él no te validan).
2. Haz las pruebas que pide el formulario de validación y guarda las evidencias: órdenes de compra, fecha y hora de cada transacción.
3. Envía el formulario. Si usas un plugin oficial hay un formulario propio; si integraste con SDK o API, usa el de tu producto.
4. Al aprobarse, recibes tu Tbk-Api-Key-Secret.
5. Cambia la configuración a producción: en los SDK, buildForProduction u Options con Environment.Production, tu código de comercio y tu llave.
6. Guarda el código y la llave en variables de entorno, nunca escritos en el código ni subidos a GitHub.
7. Haz una compra real de monto bajo y anúlala para confirmar que todo funciona.

Errores frecuentes al integrar Webpay Plus

• Error 288: lo explicamos con su solución en error 288 en Webpay.
• Error 253: ver error 253 en Webpay Plus.
• Token vencido: el token dura 5 minutos. Si creas la transacción al cargar el carrito y el cliente se demora, falla. Créalo al hacer clic en pagar.
• Error 422: el requerimiento no pasó las validaciones de datos o de negocio. Lo típico: buy_order repetida, más larga de 26 caracteres o con acentos y signos no permitidos, o monto en formato incorrecto.
• Error 401 o credenciales inválidas: mezclaste ambientes, por ejemplo tu llave de producción contra el host de integración o el código de pruebas en producción.
• Pedidos marcados como pagados sin pago: pasa cuando solo se revisa que llegue el token. Revisa siempre response_code 0 y status AUTHORIZED.
• El formulario no aparece: suele ser por cargar Webpay dentro de un iframe o por un formulario que no envía token_ws por POST.
• Error crítico en WooCommerce: Transbank informó problemas con las versiones 1.12.1, 1.12.2 y 1.13.0 del plugin y recomienda instalar la 1.14.0, que requiere PHP 8.2.

Si el problema es en una máquina física y no en la web (por ejemplo «reintente 19»), revisa errores comunes en máquinas Transbank.

Cuánto cobra Webpay Plus por venta

Integrar es gratis; lo que pagas es la comisión por cada venta. Según la página de tarifas de Transbank (26-10-2026, nuevos comercios desde el 1 de septiembre de 2026): 2,29% en crédito y 1,49% en débito y prepago, más IVA, con un mínimo por transacción de 0,003515 UF en crédito y 0,002260 UF en débito.

Para comparar con otras pasarelas y máquinas, revisa la comisión Transbank 2026, el comparativo de link de pago en Chile o usa la calculadora de comisiones.

¿No programas? Cómo cobrar con tarjeta sin integrar nada

Transbank Developers está pensado para desarrolladores. Si tienes un emprendimiento chico (una pastelería, un salón, una tienda de ropa en Instagram) y no tienes a alguien que programe, hay caminos más simples:

• Link de pago: generas un link desde una app y se lo mandas a tu clienta o cliente por WhatsApp. TUU, SumUp, Mercado Pago y Transbank lo ofrecen; las comisiones están en nuestra comparativa.
• Tienda online lista para usar: con Shopify conectas Webpay instalando una app, sin código. Ojo: en Chile Shopify cobra un 2% extra por venta en el plan Basic al usar pasarelas externas.
• Máquina para ventas en persona: si además vendes en ferias o en tu local, una máquina TUU o SumUp se activa en el día. Compara en TUU vs SumUp.

Preguntas frecuentes

¿Qué es Transbank Developers?

Es el portal oficial de Transbank para desarrolladores e integradores: documentación, API REST, SDK, plugins, credenciales y tarjetas de prueba para integrar Webpay Plus, Oneclick, Patpass y POS Integrado.

¿Cuál es el código de comercio de prueba de Webpay Plus?

597055555532, en el ambiente de integración (https://webpay3gint.transbank.cl). La llave secreta de prueba es pública y viene precargada en los SDK.

¿Cuál es la tarjeta de prueba de Webpay?

Para un pago aprobado: VISA 4051 8856 0044 6623, CVV 123 y cualquier fecha futura; luego RUT 11.111.111-1 y clave 123. Para un rechazo: Mastercard 5186 0595 5959 0568.

¿Cómo paso Webpay Plus a producción?

Necesitas tu código de comercio productivo, enviar el formulario de validación con tus evidencias y recibir tu Tbk-Api-Key-Secret. Luego configuras tu código y tu llave, con el SDK apuntando a producción.

¿Cómo sé si un pago fue aprobado?

Después de hacer commit con el token_ws, el pago está aprobado solo si response_code es 0 y status es AUTHORIZED.

¿Cuánto dura el token de Webpay?

5 minutos. Pasado ese tiempo caduca y no sirve para pagar, así que hay que crear una transacción nueva.

¿Integrar Webpay Plus tiene costo?

Los SDK, plugins y la documentación son gratis. Pagas la comisión por venta: 2,29% en crédito y 1,49% en débito y prepago, más IVA, según publico.transbank.cl/tarifas (26-10-2026).

¿Puedo usar Webpay Plus dentro de un iframe?

Transbank no lo recomienda, porque el formulario de pago podría no desplegarse. Redirige al cliente con un formulario POST.

Conclusión

Transbank Developers tiene todo lo necesario para integrar Webpay Plus: credenciales públicas para probar, SDK en seis lenguajes y plugins sin código. El camino es siempre el mismo: código de comercio, integración en pruebas, validación y llave de producción. Si tu negocio todavía no necesita una integración a medida, un link de pago o una máquina te dejan cobrar con tarjeta hoy mismo.