Pagos con Wompi

Integración completa con Wompi para procesar pagos con tarjetas de crédito, débito y PSE en Colombia. Cobros recurrentes automáticos incluidos.

Métodos de Pago Soportados

Flujo de Pago

Flujo de Datos de la Tarjeta (Alcance PCI)

El número de tarjeta y el CVV nunca tocan los servidores de PayWL ni los del cliente. Viajan directo del browser del lector a Wompi. Esto es lo que realmente cruza cada frontera del sistema:

Configuración

En el Dashboard, ve a Configuración → Integraciones → Wompi:

1. Ingresa tu Public Key (comienza con pub_)
2. Ingresa tu Private Key (comienza con prv_)
3. Configura el Events Secret para validar webhooks
4. Selecciona el ambiente: sandbox o production
5. Haz clic en "Probar Conexión" para verificar

Cobros Recurrentes

PayWL maneja automáticamente los cobros recurrentes mensuales:

• Tokenización: La tarjeta se tokeniza en el primer pago
• Renovación: 1 día antes del vencimiento se intenta el cobro
• Reintentos: Si falla, se reintenta 3 veces con backoff exponencial
• Notificación: Email al suscriptor si falla el cobro
• Cancelación: Después de 3 fallos se pausa la suscripción

Webhooks de Wompi

PayWL escucha los siguientes eventos de Wompi:

Configurar Webhook en Wompi

URL: https://engine.paywl.io/webhooks/wompi
Eventos: transaction.updated

Estados de Transacción

Integración del Checkout (para equipos de frontend de cliente)

Flujo de widget hosteado, no de API directa: Wompi tokeniza la tarjeta en un widget que el cliente mismo hostea (PayWL nunca la ve), y al terminar hace un POST real de formulario (no un callback de JS) directo al edge worker de PayWL en el propio dominio del cliente, que activa la suscripción del lado del servidor y redirige de vuelta con el resultado.

Paso 1: Obtener el public_key

Endpoint público, sin autenticación:

GET https://engine.paywl.io/edge/config?domain=<su-dominio>

{
  "wompi": { "public_key": "pub_...", "sandbox": false }
}

Si wompi viene null, el tenant todavía no tiene Wompi configurado (se hace desde Configuración → Integraciones → Wompi en el Dashboard).

Paso 1.5: Verificar identidad antes de tokenizar (Regla 4, evitar suscripciones duplicadas)

Opcional pero recomendado: antes de montar el widget de Wompi (Paso 3), llamar a este endpoint con el email (y documento de identidad, si ya se capturó en el formulario) para avisarle al usuario si ya existe una suscripción activa asociada a esos datos — antes de que cobre la tarjeta, no después.

POST https://engine.paywl.io/edge/check-identity
Content-Type: application/json

{
  "domain": "<su-dominio>",
  "email": "[email protected]",
  "document_number": "1234567890"
}

Respuesta — una de tres formas, según lo que encuentre:

// Sin ninguna coincidencia — proceder normal
{ "match": "none" }

// Ya existe una suscripción activa con ESTE MISMO email (caso normal de
// re-suscripción/encadenamiento, no es una advertencia — informativo)
{ "match": "same_email", "current_period_end": "2027-03-15T00:00:00.000Z" }

// Existe una suscripción activa con el MISMO documento de identidad pero
// bajo OTRO email — probable duplicado sin querer, mostrar advertencia
{ "match": "different_email", "masked_email": "j•••@gmail.com" }

document_number es opcional en la llamada — si no se manda (por ejemplo, el formulario todavía no lo pidió en ese punto del flujo), solo se resuelve el caso same_email/none. Este endpoint es de solo lectura y no requiere user_token: solo confirma si alguna suscripción coincide, más un email enmascarado en el caso de colisión — no expone a quién pertenece la cuenta más allá de eso.

Paso 2: El formulario

<form id="checkout-form" action="https://<su-dominio>/__paywl/wompi-token-callback" method="POST">
  <input type="hidden" name="plan_id" value="<uuid del plan elegido>" />
  <input type="hidden" name="payer_email" value="<email del usuario logueado>" />
  <input type="hidden" name="payer_name" value="<opcional, ver nota abajo>" />
  <input type="hidden" name="document_type" value="<CC | CE | NIT | TI | PASSPORT | OTHER>" />
  <input type="hidden" name="document_number" value="<opcional si el tenant no tiene Siigo activo>" />
  <input type="hidden" name="trial_policy_id" value="<opcional, si aplica trial>" />
  <input type="hidden" name="return_url" value="<ruta relativa a dónde volver, ver nota abajo>" />
  <input type="hidden" name="confirmed_duplicate" value="<'true' solo si el usuario ya confirmó continuar tras la advertencia del Paso 1.5>" />
  <input type="hidden" name="discount_code" value="<opcional, código de cupón ya validado>" />
  <!-- el script de Wompi va ACÁ, ver Paso 3 -->
</form>

user_token no va como campo del form — se resuelve del lado del servidor leyendo la cookie de sesión del usuario en su dominio. No hace falta hacer nada especial más allá del login normal del sitio. confirmed_duplicate se omite (o se manda distinto de "true") en el caso normal — solo se setea a "true" cuando el usuario ya vio la advertencia de identidad duplicada del Paso 1.5 y decidió seguir de todas formas. discount_code es opcional — ver Suscripciones y Trials → Códigos de Descuento para el flujo completo de previsualización y validación.

Paso 3: Montar el widget de Wompi

<script
  src="https://checkout.wompi.co/widget.js"
  data-render="button"
  data-widget-operation="tokenize"
  data-public-key="<public_key del Paso 1>"
></script>

Paso 4: Después del pago

Wompi tokeniza, agrega un campo oculto payment_source_token al form, y lo submitea solo (navegación real de browser, no un fetch). El edge worker recibe ese POST, activa la suscripción, y redirige de vuelta a return_url con query params:

?paywl_status=success&paywl_subscription_id=<uuid>
# o
?paywl_status=error&paywl_message=<motivo>
# o, específicamente cuando el checkout se bloqueó por Regla 4 sin
# confirmed_duplicate=true (ver Paso 1.5 y Paso 2):
?paywl_status=error&paywl_message=<motivo>&paywl_error_code=IDENTITY_COLLISION&paywl_masked_email=j%E2%80%A2%E2%80%A2%E2%80%A2%40gmail.com
# o, si falta el documento y el tenant tiene Siigo activo (ver nota en Paso 2):
?paywl_status=error&paywl_message=<motivo>&paywl_error_code=DOCUMENT_REQUIRED
# o, si el usuario ya tiene una suscripción activa (ver "Ya tiene un plan activo" abajo):
?paywl_status=error&paywl_message=<motivo>&paywl_error_code=ALREADY_SUBSCRIBED&paywl_already_subscribed_subscription_id=<uuid>

paywl_error_code y los campos que lo acompañan (paywl_masked_email, paywl_already_subscribed_subscription_id) solo vienen presentes en su caso puntual — permiten que la página de retorno distinga cada motivo específico de cualquier otro error (tarjeta rechazada, datos faltantes, etc.) sin tener que parsear paywl_message.

Ya tiene un plan activo (ALREADY_SUBSCRIBED)

Si el usuario logueado ya tiene una suscripción activa, el checkout de compra nueva se bloquea antes de cobrar la tarjeta — no cancela la suscripción vieja ni cobra el plan nuevo por encima. En vez de eso, hay que redirigirlo al flujo de cambio de plan (con prorrateo real), que ya existe y no requiere el widget de Wompi de nuevo:

# 1. Previsualizar el prorrateo (solo lectura)
POST https://engine.paywl.io/edge/change-plan-preview
Content-Type: application/json

{ "domain": "<su-dominio>", "user_token": "<misma cookie de sesión>",
  "subscription_id": "<paywl_already_subscribed_subscription_id>",
  "new_plan_id": "<el ID (UUID) del plan, NO el slug>" }

{
  "type": "upgrade",
  "current_plan": { "id": "...", "name": "...", "price_cents": 880000, "currency": "COP", "billing_interval": "monthly" },
  "new_plan": { "id": "...", "name": "...", "price_cents": 1290000, "currency": "COP", "billing_interval": "monthly" },
  "credit_cents": 848000,
  "charge_cents": 442000,
  "effective_at": "now"
}

type es "upgrade" (plan más caro), "downgrade" (más barato) o "lateral" (mismo precio — cambio de plan sin ningún efecto financiero). En upgrade, effective_at es "now" — cambia de inmediato y charge_cents se cobra ya, con credit_cents ya descontado por el tiempo no usado del plan actual. En downgrade, effective_at es "next_renewal" — no se cobra nada ahora, el cambio de precio aplica recién en la siguiente renovación. En lateral, effective_at es "now" y credit_cents/charge_cents siempre son 0 — el cambio de plan aplica de inmediato sin cobrar ni acreditar nada, porque el precio no cambia.

Después de mostrarle esto al usuario, si confirma:

# 2. Confirmar — mismo body, endpoint distinto
POST https://engine.paywl.io/edge/change-plan
Content-Type: application/json

{ "domain": "<su-dominio>", "user_token": "<misma cookie de sesión>",
  "subscription_id": "<el mismo id>", "new_plan_id": "<el mismo UUID usado en el preview>" }

Cómo probar

Tarjetas de test en modo sandbox:

Fecha de expiración y CVC: cualquier valor futuro / 3 dígitos sirve en sandbox.

Checklist de prueba completa:

• El botón de Wompi se renderiza (si no aparece, revisar que el script esté como hijo directo del form — Paso 3)
• Tarjeta Aprobada: la suscripción queda active de una
• Tarjeta Pendiente: queda en estado intermedio hasta que llega el webhook de Wompi, después pasa a active sola
• Tarjeta Rechazada: vuelve a return_url con paywl_status=error
• Confirmar en el Dashboard (Suscriptores) que la suscripción nueva aparece con el plan y el email correctos
• Probar estando no logueado: debería fallar (el callback necesita user_token de la sesión) — confirmar que el mensaje de error tiene sentido para el usuario final
• Probar el caso de identidad duplicada (Paso 1.5): con dos cuentas de prueba que compartan document_number pero tengan emails distintos, confirmar que check-identity devuelve different_email para la segunda, que el checkout sin confirmed_duplicate se bloquea con paywl_error_code=IDENTITY_COLLISION, y que reintentando con confirmed_duplicate=true sí se crea la suscripción
• Si el tenant tiene Siigo activo: probar sin document_number — confirma que se bloquea con paywl_error_code=DOCUMENT_REQUIRED sin cobrar la tarjeta, y que reintentando con el documento sí se completa
• Confirmar que return_url como ruta relativa (ej. /suscribirse/resultado) efectivamente vuelve ahí, no a la raíz del dominio
• Con un usuario que ya tenga una suscripción activa: intentar comprar un plan nuevo — confirma que se bloquea con paywl_error_code=ALREADY_SUBSCRIBED (y paywl_already_subscribed_subscription_id) sin cobrar ni cancelar nada, y que /edge/change-plan-preview con ese ID sí calcula un prorrateo real