¿Cómo integro PayPal para el seguimiento de ingresos?

Conectar PayPal permite a Zenovay mostrar los ingresos junto a tus datos de tráfico — qué fuente de marketing produjo al cliente que pagó, en qué página convirtió, qué campaña cerró el trato.

Necesitas tres cosas de tu cuenta de PayPal Developer: un Client ID, un Client Secret y un Webhook ID. Creas el webhook en tu panel de PayPal (Zenovay te muestra la URL exacta para pegar) y copias su ID devuelta a Zenovay. Recomendamos configurar primero el Sandbox para verificar que todo funciona, y luego cambiar a Live.

⚠️ Importante — consejo de pruebas que deberías leer primero

El Webhooks Simulator de PayPal (el botón "Send Test" en el PayPal Developer Dashboard) envía eventos simulados que no se pueden verificar por firma por diseño. Este es un comportamiento documentado de PayPal — el simulador vincula las firmas a un WEBHOOK_ID de marcador de posición, no a tu Webhook ID real, así que la API de verificación siempre devuelve FAILURE para los eventos del simulador.

Para verificar que tu integración funciona realmente, haz un checkout real en Sandbox (Paso 5 más abajo) — eso produce un evento firmado correctamente que Zenovay puede verificar.

Paso 1: crear una app REST API de PayPal — y habilitar la función Webhooks

⚠️ Habilita la función Webhooks en tu app.

Las nuevas apps REST API de PayPal vienen por defecto con "Accept payments only". Tu app necesita la función Webhooks habilitada para poder crear y verificar webhooks. Esta es una configuración única de 30 segundos.

1. 1

   Inicia sesión en PayPal Developer

   Ve a developer.paypal.com e inicia sesión con tu cuenta business de PayPal. Es gratis; tarda alrededor de un minuto.

2. 2

   Abre Apps & Credentials

   En el dashboard, haz clic en Apps & Credentials. Cambia a Sandbox para pruebas, o a Live para producción.

3. 3

   Crea una app nueva

   Haz clic en Create App. Ponle un nombre como "Zenovay Analytics". Elige Merchant como tipo de app. Haz clic en Create App.

4. 4

   Copia tu Client ID y Secret

   PayPal muestra tu Client ID (cadena alfanumérica larga) y Secret (haz clic en Show para revelarlo). Mantén esta pestaña abierta — los pegarás en Zenovay en el Paso 3.

5. 5

   Marca la casilla de la función Webhooks

   Sigue en la página de configuración de tu app y baja hasta la sección Features (a veces etiquetada como App settings). Verás casillas como Accept payments, Vault, Payouts, Subscriptions, Log in with PayPal y Webhooks.

   Marca la casilla Webhooks y luego haz clic en Save Changes al final de la página.

   No es necesario regenerar tu Client Secret — el nuevo permiso se aplica a los nuevos tokens OAuth de inmediato.

Paso 2: crear el webhook en PayPal y copiar su Webhook ID

Abre la configuración de tu sitio en Zenovay y ve a la pestaña Revenue (bajo la sección Analytics), luego haz clic en la tarjeta PayPal. El formulario muestra una URL webhook copiable que ya incluye tu ID de sitio — cópiala, luego registra el webhook del lado de PayPal.

1. 1

   Copia tu URL webhook de Zenovay

   En la tarjeta PayPal en Zenovay, copia la URL webhook que se muestra en la parte superior del formulario. Se ve así:

   https://api.zenovay.com/api/webhooks/paypal/YOUR_WEBSITE_ID
   

   La URL ya está llena con tu ID de sitio — no necesitas construirla tú mismo.

2. 2

   Añade el webhook en PayPal

   De vuelta en PayPal Developer, dentro de la configuración de tu app, baja hasta Sandbox Webhooks (o Live Webhooks). Haz clic en Add Webhook y pega la URL que copiaste.

3. 3

   Suscríbete a los eventos correctos

   Marca como mínimo:

   • Payment capture completed
   • Payment capture refunded
   • Checkout order approved (opcional; se registra para observabilidad)

   Haz clic en Save. PayPal genera un Webhook ID — guárdalo para el Paso 3.

Paso 3: conectar en Zenovay

Sigue en la tarjeta PayPal en la pestaña Revenue de tu configuración de sitio:

1. 1

   Pega tus tres credenciales

   • Client ID — del Paso 1
   • Client Secret (este es el campo API Key) — del Paso 1
   • Webhook ID — el ID que PayPal generó en el Paso 2 (requerido)
2. 2

   Elige Sandbox o Live

   Haz coincidir el entorno que configuraste en el Paso 1. Sandbox usa api-m.sandbox.paypal.com; Live usa api-m.paypal.com. Mezclar modos hará fallar la verificación de firma.

3. 3

   Haz clic en Guardar

   Zenovay valida tus credenciales obteniendo un token de acceso OAuth2, luego verifica el Webhook ID contra PayPal. La tarjeta cambia a Conectado.

Paso 4: etiqueta tus pedidos con el ID del visitante (recomendado)

Para que la atribución pago-a-fuente-de-tráfico funcione con la mayor precisión, define el ID anónimo de Zenovay del visitante como custom_id al crear el pedido de PayPal en tu servidor:

// Ejemplo en Node.js usando @paypal/paypal-server-sdk
const visitorId = req.cookies['zv_visitor_id']; // o como tu cliente lo pase

await paypalClient.ordersCreate({
  body: {
    intent: 'CAPTURE',
    purchase_units: [{
      amount: { currency_code: 'USD', value: '42.00' },
      custom_id: visitorId, // ← UUID del visitante de Zenovay va aquí
    }],
  },
});

Cuando la captura se complete, Zenovay lee purchase_units[0].custom_id y une el pago con la sesión del visitante — incluida la fuente, la campaña y las páginas que visitó antes de pagar.

Si no defines custom_id, la atribución todavía funciona mediante la dirección de email del pagador, pero es menos precisa (solo coincide si el visitante se identificó previamente con el mismo email).

Cómo funciona la atribución

Zenovay atribuye cada pago a una fuente de tráfico y te permite cambiar entre varios modelos de atribución desde la pestaña Revenue:

• Last Touch (predeterminado) — 100% del crédito va al último canal antes de la conversión. Bueno para medir qué cierra tratos.
• First Touch — 100% del crédito va al canal que primero trajo al visitante. Bueno para medir qué genera descubrimiento.
• Linear — divide el crédito equitativamente entre cada canal que usó el visitante.
• Position-Based — 40% al primer canal, 40% al último, el 20% restante entre todo lo intermedio.
• Time-Decay — más crédito a canales más cercanos a la conversión, en una vida media de 7 días.

Elige el modelo en la pestaña Revenue; el desglose se recalcula para el modelo que elijas.

Paso 5: pruebas en Sandbox — usa un checkout real, no el Simulator

No uses el Webhooks Simulator de PayPal para probar. Los eventos del Simulator deliberadamente no se pueden verificar por firma (PayPal lo documenta) — siempre fallarán la comprobación de verificación de Zenovay. En su lugar, usa un checkout real en Sandbox, como se describe abajo.

La forma correcta de verificar tu integración Sandbox:

1. PayPal Developer Dashboard → Sandbox → Accounts. Deberías ver una cuenta sandbox Personal (buyer) por defecto con un email + contraseña ficticios — estas son las credenciales del comprador de prueba.
2. Desde tu aplicación o el SDK de PayPal, crea un pedido sandbox que apunte a tu client_id de sandbox (define purchase_units[0].custom_id = visitorId si quieres la mejor atribución — ver Paso 4 arriba).
3. Completa el checkout con la cuenta de comprador sandbox del Paso 1.
4. En aproximadamente 10 segundos, PayPal envía un webhook real y firmado PAYMENT.CAPTURE.COMPLETED a Zenovay. Verifica que llegó abriendo la pestaña Revenue en tu dashboard de sitio — la captura debería aparecer con el email sandbox del comprador + el importe.

Si la captura no aparece después de aproximadamente 30 segundos:

• Revisa el badge de Estado de verificación en la tarjeta PayPal en tu configuración de Revenue — muestra el error más reciente.
• Confirma que el modo Sandbox vs Live coincide: un webhook Sandbox disparado contra una integración Live (o viceversa) hará fallar la verificación de firma.
• Confirma que el webhook sigue registrado en PayPal: PayPal Dashboard → tu app → Webhooks. Si fue eliminado, vuelve a agregarlo y pega el nuevo Webhook ID en Zenovay.

Cambiar de Sandbox a Live

Cuando estés listo para producción:

1. En PayPal Developer, crea una app REST API Live y un Webhook Live (Paso 1 + Paso 2 de nuevo en la pestaña Live — el webhook Live obtiene su propio Webhook ID).
2. En Zenovay, abre la tarjeta PayPal, pega las credenciales Live y el Webhook ID Live, cambia el conmutador a Live y haz clic en Guardar.

PayPal envía los eventos al entorno que coincida con tu Webhook ID registrado, así que mantén las credenciales y el Webhook ID del mismo entorno juntos.

Desconectar

Abre la configuración de tu sitio → pestaña Revenue → haz clic en la tarjeta PayPal → Desconectar.

De forma predeterminada, desconectar solo elimina tus credenciales de PayPal. Tus registros de pagos existentes, historial de atribución y datos del panel de Revenue permanecen intactos (según la ventana de retención de datos de tu plan). Puedes volver a conectarte en cualquier momento y continuar donde lo dejaste.

Opcional: también eliminar los datos históricos de PayPal

El diálogo de desconexión incluye una casilla de verificación: "También eliminar permanentemente N registros de PayPal (X € en total)". Márcala solo si quieres empezar de cero — por ejemplo, para retirar una integración de prueba o hacer limpieza de privacidad.

Cuando está marcada, Zenovay:

• eliminará todas las filas payment_events de PayPal para este sitio
• eliminará todas las filas payments de PayPal para este sitio
• vaciará el campo paypal_customer_id en cada usuario identificado (el registro de usuario en sí se preserva — conserva su ID de Stripe, etc.)

La eliminación se ejecuta en una sola transacción — si algún paso falla, los tres se revierten, por lo que nunca te quedas en un estado a medio borrar. La acción es irreversible.

No olvides eliminar el webhook del lado de PayPal

Desconectar en Zenovay solo detiene a Zenovay de aceptar eventos. PayPal seguirá disparando el webhook hacia nuestro endpoint hasta que tú lo elimines en tu PayPal Developer Dashboard:

1. Abre https://developer.paypal.com/dashboard/applications/
2. Haz clic en tu app PayPal REST API.
3. Abre la sección Webhooks.
4. Encuentra el webhook que apunta a https://api.zenovay.com/api/webhooks/paypal/{your-website-id} y elimínalo.

Hasta que lo elimines del lado de PayPal, nuestro endpoint responderá 410 Gone a cada entrega. PayPal abandona los reintentos después de 410 — así que es principalmente cosmético, pero es buena higiene y evita que el webhook llene los propios logs de reintento de PayPal.

Limitaciones

• Una cuenta de PayPal por sitio de Zenovay. Si aceptas pagos a través de varias cuentas de PayPal, configura cada una en su propio sitio de Zenovay.
• La conexión es saisie manuelle únicamente. No hay redirección OAuth "Log in with PayPal" — copias el Client ID, Client Secret y Webhook ID directamente.

Solución de problemas

"Verification failed" en un webhook de prueba real

Lo más probable es un desajuste Sandbox/Live — un webhook disparado por sandbox.paypal.com contra credenciales marcadas como Live (o viceversa) fallará la verificación de firma. Comprueba que el conmutador en la tarjeta PayPal coincide con el entorno de tus credenciales.

Si has usado el Webhooks Simulator de PayPal, eso es una limitación conocida — los eventos del simulador no se pueden verificar por firma por diseño (PayPal vincula la firma a un literal WEBHOOK_ID de marcador de posición, no a tu Webhook ID real). Prueba siempre con un checkout real en Sandbox en su lugar.

« NOT_AUTHORIZED » / error 403

Esto significa generalmente que la función Webhooks no está habilitada en tu app REST API de PayPal, o estás usando un cuenta sandbox Personal donde los webhooks requieren una cuenta sandbox Business.

Solución:

1. Abre https://developer.paypal.com/dashboard/applications y haz clic en tu app.
2. Asegúrate de estar en la pestaña correcta (Sandbox o Live) — tienen ajustes separados.
3. Baja hasta la sección Features (debajo del bloque del Client ID / Secret).
4. Marca la casilla Webhooks.
5. Haz clic en Save Changes al final de la página.
6. Si estás en Sandbox, confirma que estás usando una cuenta sandbox Business, no una Personal.

No necesitas regenerar el Client Secret. El nuevo permiso se aplica a los nuevos tokens OAuth de inmediato.

Has alcanzado el límite de 10 webhooks en tu app de PayPal

PayPal limita cada app REST API a 10 webhooks. Si has registrado Zenovay varias veces (por ejemplo, en muchos sitios de Zenovay) puede que llegues a este límite. O bien elimina los webhooks que no uses en https://developer.paypal.com/dashboard/applications, o abre la sección Avanzado (opcional) del formulario de PayPal en Zenovay y pega el ID de un webhook existente en lugar de dejar que Zenovay lo cree automáticamente.

Lecturas relacionadas

• Integración de ingresos con Stripe
• Visión general de webhooks
• Seguimiento de ingresos de e-commerce
• Instalar el script de seguimiento