Cuando arranqué la integración de pagos para ReclamaAI, asumí que sería un fin de semana. Wompi tiene SDK, documentación clara y un sandbox que funciona. Tres semanas después seguía corrigiendo edge cases. Esta es la lista de cosas que ojalá alguien me hubiera dicho antes.
Por qué Wompi y no Stripe
Stripe en Colombia es posible pero incómodo: no tiene PSE nativo, las comisiones son en USD, y para reembolsos en pesos toca pasar por conversiones que confunden al usuario. Wompi nació en Bogotá, integra los métodos que la gente realmente usa aquí (PSE, Nequi, Bancolombia transfer, tarjetas locales), y los webhooks llegan en español, en pesos colombianos, sin sorpresas.
La contraparte: la API de Wompi es más joven que la de Stripe. Hay endpoints sin documentar, mensajes de error inconsistentes y un "modo de eventos" que cambió dos veces en seis meses. Si vienes acostumbrado a la pulcritud de Stripe, prepárate para improvisar.
El webhook que llegó dos veces
La trampa más cara fue idempotencia. Wompi puede reintentar un webhook si tu servidor tarda más de unos segundos en responder, y el reintento llega con el mismo transaction.id pero con un nuevo event.id. Si solo desduplicas por evento, el usuario termina con créditos duplicados.
Lo que funciona: aplicar idempotencia explícita usando el transaction.id como clave, no el event.id. La forma concreta no importa tanto como el principio: antes de aplicar cualquier efecto de un pago (cargar créditos, marcar una orden como pagada, mandar un correo de confirmación), debe haber una guarda que rechace silenciosamente el reintento si ya procesaste ese transaction.id. Sin esa guarda, vas a tener correos duplicados y créditos dobles tarde o temprano.
PSE: el método más usado y el que más rompe
PSE redirige al usuario al banco, donde autoriza el débito. Cuando vuelve, puede pasar una de cuatro cosas: aprobado, rechazado, pendiente, o nunca volver. La cuarta es la peor — el usuario cierra la pestaña porque su banco lo expulsó tras 10 minutos, y la transacción queda en limbo.
La lección: nunca confíes en el redirect. La fuente de verdad es el webhook, no la URL de retorno. Nuestro flujo es: el usuario vuelve a una página intermedia que dice "estamos confirmando tu pago, esto puede tardar hasta 2 minutos", hace polling al backend, y solo cuando el webhook confirma actualizamos el estado. Si tras 3 minutos no hay webhook, le mostramos un mensaje claro: "tu banco aún no respondió, revisaremos en segundo plano y te avisamos por correo".
Reembolsos: el detalle del IVA
Colombia tiene IVA del 19% en servicios digitales y eso pinta cada cobro. Cuando reembolsas un pago, Wompi reembolsa el monto bruto, pero tu contabilidad necesita rastrear el IVA por separado. Si no lo haces desde el día uno, vas a estar reconciliando manualmente cuando llegue declaración.
Solución: en cada transacción guardamos tres campos: amount_gross, amount_iva, amount_net. El amount_gross es lo que el usuario ve y lo que Wompi mueve; los otros dos son el desglose. Los reembolsos guardan el mismo desglose, y la conciliación con DIAN es ya solo un query.
Lo que sigue
Wompi todavía no tiene billing recurrente robusto en Colombia, así que las suscripciones las manejamos a mano: créditos que se vencen, recordatorios de recompra, descuentos por paquete. No es elegante pero funciona y nos da control. Cuando Wompi lance subscriptions oficiales, evaluaremos migrar — pero solo si la API es estable. Tras tres semanas integrando esto, aprendí que la cosa más cara no es el código que escribes, es el código que reescribes cuando el proveedor cambia el contrato sin avisar.