Cómo crear tu cuenta de Wompi y configurar las llaves

Wompi es la pasarela de pagos del grupo Bancolombia y una de las formas más usadas para aceptar tarjetas, PSE, Nequi y Bancolombia a Botón en Colombia. Conectarla a tu tienda toma tres etapas: crear la cuenta, copiar las llaves y configurar la URL de eventos (el webhook que le avisa a tu tienda cuando un pago se aprueba). Aquí las explicamos una por una, en orden y sin dar nada por sentado.

Tienly no está afiliado ni asociado con Wompi. Cada comercio se registra directamente con la pasarela y usa sus propias llaves. Las tarifas y los tiempos de desembolso los define Wompi.

Qué necesitas antes de empezar

El registro se hace en línea y puedes completarlo desde el celular. Ten a la mano, según tu caso:

• Persona natural: tu documento de identidad, el RUT actualizado y sin contraseña, y el número de una cuenta bancaria a tu nombre. Wompi indica que las personas naturales no necesitan certificado de Cámara de Comercio para vincularse.
• Persona jurídica: documento de identidad del representante legal, RUT actualizado sin contraseña y una cuenta bancaria asociada al NIT de la empresa.
• Datos de contacto y tu actividad económica.
• Buena luz y buena conexión: en algún punto te pedirán una selfie para verificar que eres el titular.

Detalle que frena a mucha gente: el PDF del RUT debe estar sin contraseña. Si lo descargaste protegido, vuelve a generarlo o quítale la clave antes de subirlo.

Etapa 1: crear tu cuenta en Wompi paso a paso

1. Entra al registro de comercios en el sitio oficial de Wompi y crea tu usuario con tu correo y una contraseña.
2. Elige el tipo de persona: natural si vas a recibir pagos con tu cédula o RUT, jurídica si los vas a recibir con el NIT de tu empresa.
3. Diligencia el formulario con tus datos de contacto, tu actividad económica y la información de la cuenta bancaria donde quieres recibir los desembolsos.
4. Carga los documentos exactamente como los pide el formulario. Archivos legibles, completos y sin contraseña.
5. Verifica tu identidad con la selfie o la validación por cámara que te solicite el proceso.
6. Firma el contrato digitalmente. Te llega un correo con el enlace de firma; no necesitas imprimir nada.
7. Espera la confirmación de activación al correo que registraste. Mientras tanto ya puedes explorar el ambiente de pruebas.

Un consejo: usa un correo al que realmente tengas acceso y que revises. Toda la comunicación de activación, y después las notificaciones de desembolso, llegan ahí.

Etapa 2: entender y copiar tus llaves

Aquí es donde la mayoría se confunde, porque Wompi no maneja una llave sino cuatro valores, y además existen dos ambientes. Vamos por partes.

Los dos ambientes

• Sandbox (pruebas): transacciones falsas para probar la integración. No mueve dinero real.
• Producción: transacciones reales con dinero real.

Son ambientes completamente independientes: lo que hagas en uno no aparece en el otro, y cada uno tiene su propio juego de llaves y su propia URL de eventos.

Los cuatro valores

Dónde encontrarlas

1. Inicia sesión en tu panel de comercio de Wompi.
2. Ve a la sección de tu cuenta.
3. Las llaves pública y privada están bajo el bloque de llaves del API para integración técnica.
4. Los secretos de eventos e integridad están bajo el bloque de secretos para integración técnica.
5. Fíjate en el selector de modo de prueba / modo de producción: los valores cambian según el modo en el que estés.

Copia y pega siempre. No transcribas a mano y no dejes espacios al inicio ni al final: un carácter de más es la causa número uno de un “llave inválida”.

Etapa 3: pegar las llaves en tu tienda

1. Entra al panel de administración de tu tienda Tienly.
2. Ve a [RUTA: Configuración → Pagos → Wompi].
3. Selecciona el modo que vas a usar: pruebas o producción.
4. Pega la llave pública, la llave privada, el secreto de eventos y el secreto de integridad del mismo modo que seleccionaste.
5. Guarda y activa Wompi como método de pago.

Regla de oro: nunca mezcles ambientes. Si estás en producción, los cuatro valores deben empezar por pub_prod_, prv_prod_, prod_events_ y prod_integrity_. Mezclar uno solo de pruebas hace que todo falle con errores difíciles de leer.

Etapa 4: configurar la URL de eventos (el webhook)

Qué hace y por qué importa

Cuando un cliente paga, tu tienda no siempre se entera de inmediato. La URL de eventos es la dirección a la que Wompi le envía a tu tienda un mensaje automático cada vez que una transacción cambia de estado. Sin ella, un pago aprobado por PSE puede quedar figurando como pendiente en tu panel aunque el dinero ya haya entrado.

Wompi hace una petición POST con un JSON que incluye el evento y los datos de la transacción, y espera que tu servidor responda con un código 200. Si no lo recibe, considera que la notificación falló y reintenta hasta tres veces durante las siguientes 24 horas: el primer reintento a los 30 minutos, el segundo a las 3 horas y el último a las 24 horas.

Cómo configurarla

1. Copia la URL de eventos que te entrega tu tienda Tienly en [RUTA: Configuración → Pagos → Wompi]. Se ve parecida a https://tutienda.tienly.co/webhooks/wompi [PLACEHOLDER: reemplazar por la URL real].
2. Entra a tu panel de comercio de Wompi.
3. Busca el campo de URL de eventos en la configuración de tu cuenta.
4. Pega la URL completa, sin quitarle ni un carácter, y guarda.
5. Repite el proceso en el otro ambiente. Debes configurar una URL de eventos en pruebas y otra en producción, por separado.

Dos requisitos innegociables: la URL debe ser HTTPS y debe ser pública. Una dirección local tipo localhost nunca va a recibir el evento, porque Wompi no puede alcanzarla desde internet.

Qué le llega a tu tienda

El evento más importante es transaction.updated, que se dispara cuando una transacción llega a un estado final. El JSON trae, entre otros datos, el identificador de la transacción, la referencia que tú generaste, el monto en centavos, el método de pago y el estado, que puede ser APPROVED, DECLINED, VOIDED o ERROR.

Etapa 5: probar antes de vender de verdad

1. Deja tu tienda en modo de pruebas con las llaves _test_.
2. Haz una compra completa desde la vista pública de tu tienda, como lo haría un cliente.
3. Verifica tres cosas: que la transacción aparece en el panel de Wompi, que el pedido quedó registrado en tu tienda y que el estado del pedido cambió solo, sin que tú lo tocaras.
4. Prueba también un pago declinado, no solo uno aprobado. Necesitas saber qué ve el cliente cuando el pago falla.
5. Cuando las tres cosas funcionen, cambia a producción: reemplaza los cuatro valores por los de producción y configura la URL de eventos del ambiente de producción.
6. Haz una compra real de monto bajo con tu propia tarjeta y confirma que todo el circuito cierra.

Para desarrolladores: validar la firma del evento

Esta sección solo aplica si estás construyendo tu propia integración. Si usas Tienly, la validación ya está implementada y no tienes que hacer nada.

Cualquiera que conozca tu URL de eventos podría intentar enviarte un POST falso diciendo que una transacción fue aprobada. Por eso Wompi firma cada evento. La verificación consiste en recalcular esa firma de tu lado y compararla con la que llega:

1. Toma los valores de los campos que indica el arreglo signature.properties, en ese orden exacto, leyéndolos del objeto data.
2. Concaténalos y agrega el timestamp del evento.
3. Agrega al final tu secreto de eventos (prod_events_…).
4. Calcula el hash SHA-256 de esa cadena.
5. Compáralo con el checksum que llega en el evento. Si no coincide, descarta la petición.

Dos recomendaciones que evitan incidentes reales: nunca marques un pedido como pagado basándote solo en la redirección del navegador, porque el cliente puede cerrar la pestaña antes y porque PSE puede tardar minutos en confirmarse; y haz tu endpoint idempotente, porque los reintentos significan que puedes recibir el mismo evento más de una vez.

La especificación completa y actualizada está en la documentación oficial de Wompi para desarrolladores.

Errores comunes y cómo resolverlos

Seguridad: qué nunca debes compartir

• La llave privada, el secreto de eventos y el secreto de integridad van únicamente en tu servidor. Nunca en el navegador, ni en un repositorio público, ni en una captura de pantalla.
• Nadie legítimo te va a pedir esas llaves por WhatsApp, correo o redes sociales. Si alguien lo hace, es fraude.
• La llave pública sí puede ser visible: está diseñada para eso.
• Si crees que un secreto quedó expuesto, contacta a Wompi para rotarlo y actualiza el valor en tu tienda.
• Activa la verificación en dos pasos en tu cuenta de Wompi.

Preguntas frecuentes

¿Necesito Cámara de Comercio para registrarme en Wompi?

Según la información de soporte de Wompi, las personas naturales no requieren certificado de Cámara de Comercio para vincularse. Para persona jurídica, ten a la mano el RUT actualizado y la cuenta bancaria asociada al NIT.

¿Necesito ser cliente de Bancolombia?

No. Wompi es del grupo Bancolombia, pero puedes recibir tus desembolsos en cuentas de otros bancos. Confirma las condiciones vigentes directamente con Wompi.

¿Cuánto cobra Wompi por transacción?

La tarifa la define Wompi y varía según el método de pago y el volumen del comercio. Consúltala siempre en su sitio oficial antes de fijar tus precios. Tienly no cobra ninguna comisión adicional sobre tus ventas.

¿La URL de eventos es obligatoria?

Para Wompi no lo es, pero para tu tienda sí es lo recomendable: sin ella, los pedidos no cambian de estado automáticamente y te toca confirmar cada pago a mano.

¿Puedo usar las mismas llaves en pruebas y en producción?

No. Son ambientes independientes, con llaves distintas y URL de eventos distintas. Mezclarlas es la causa más frecuente de fallas en la integración.

¿Qué pasa si mi servidor estaba caído cuando llegó el evento?

Wompi reintenta hasta tres veces en las siguientes 24 horas: a los 30 minutos, a las 3 horas y a las 24 horas. Si aun así no se recibe, tendrás que conciliar ese pago manualmente.

Sigue leyendo: Cómo configurar Mercado Pago: credenciales y webhook · Vender por WhatsApp con pago contra entrega