Por qué las integraciones de pagos controladas por Webhook son importantes
Los comerciantes que abonan las comisiones de sus socios de forma automática reducen el esfuerzo manual, evitan errores y aceleran las liquidaciones. Affilentra proporciona exportaciones de pagos y webhooks como puntos de entrega. En la práctica se necesita una pequeña middleware de integración que reciba los datos de exportación, los transfiera a proveedores externos de pagos (PayPal Payouts, Wise, Stripe Connect), informe los cambios de estado y genere justificantes contables. Este artículo muestra con precisión qué configuraciones y pasos son necesarios.
Resumen breve: arquitectura y responsabilidades
- Affilentra: genera exportaciones de pagos y dispara eventos de webhook con los lotes de pago.
- Middleware (su sistema o un pequeño servicio conector): valida el webhook, mapea campos, llama a las APIs del proveedor, procesa callbacks de los proveedores, crea justificantes y escribe el estado de vuelta en Affilentra.
- Proveedor de pagos (PayPal, Wise, Stripe Connect): ejecuta los pagos y proporciona referencias de pago / webhooks para el estado final.
Requisitos antes de la integración
- Instalación de Affilentra (self‑hosted) con el sistema de webhooks y la función de exportación habilitados. SSL para el endpoint del webhook.
- Cuenta y credenciales API en los proveedores destino (acceso sandbox para pruebas).
- Middleware con endpoint HTTPS, almacenamiento persistente (BD) y capacidad para generar archivos/PDFs y adjuntarlos a Affilentra.
Paso 1: definir correctamente la exportación de pagos en Affilentra
Configure en Affilentra una exportación de pagos que proporcione todos los campos necesarios. Formato recomendado: JSON o CSV con UTF‑8. Campos importantes:
- payout_id (ID interna única)
- partner_id / partner_identifier
- payee_type (email | iban | account_id)
- payee_address (correo electrónico, IBAN, ID de cuenta bancaria)
- amount (decimal, p. ej. 123.45)
- currency (código ISO, p. ej. EUR)
- gross / net / fee (si deben desglosarse)
- description / reference
Importante: incluya un campo para una referencia externa (provider_reference) y un campo de estado (pending / sent / failed / reconciled) — la middleware los rellenará.
Paso 2: configurar el webhook en Affilentra
- Crear un endpoint de webhook en Affilentra que envíe un evento al ejecutar una exportación de pagos (p. ej. payout_exported).
- Proteger el evento del webhook con una firma HMAC (Shared Secret). La middleware debe verificar esta firma contra las cargas recibidas.
- Configurar reintentos en Affilentra (p. ej. 3 intentos con backoff exponencial) y documentar los errores en logs.
Paso 3: Middleware – flujo y puntos de implementación
La middleware es el elemento central. Tareas principales:
- Validación de Webhook (firma, esquema, comprobación de duplicados).
- Mapeo: convertir la exportación de Affilentra al payload del proveedor.
- Llamada al proveedor: crear lotes, establecer Idempotency‑Keys, gestionar errores de API.
- Gestión de estado: procesar las respuestas del proveedor, notificar el estado de vuelta a Affilentra.
- Generación de justificantes: generar PDF/CSV/JSON, adjuntarlos al pago y remitirlos a contabilidad.
Ejemplos de mapeo (orientados a la práctica)
- PayPal: mapear payee_address → receiver_email, amount + currency → amount, utilice sender_batch_id = payout_id.
- Wise: si hay IBAN, crear el Recipient, generar una Quote (si hay cambio de divisa) y Transfer con reference = payout_id.
- Stripe Connect: para cuentas conectadas utilice el parámetro destination o envíe Payouts en nombre del Connected Account; si procede, ejecute primero un Transfer.
Particularidades del proveedor y consejos
- PayPal Payouts: utilice Batch‑Payouts para mayor eficiencia; establezca sender_batch_id para idempotencia; almacene payout_item_id y batch_status para reconciliación posterior.
- Wise: cree el destinatario (recipient) una vez y reutilice la recipient_id; tenga en cuenta el posible paso de Quote en cambios de divisa.
- Stripe Connect: compruebe si su flujo debe usar Transfers a cuentas conectadas o cuentas bancarias externas; utilice Idempotency‑Keys y liste balance_transfers.
Notificación de estado a Affilentra y reconciliación
Así garantiza procesos de contabilización fiables:
- Inmediatamente tras la respuesta del proveedor: actualice los Payouts de Affilentra con provider_reference, status = sent (o failed) e información de fees.
- Implemente un listener para los Webhooks del proveedor (p. ej. Webhooks de PayPal/Stripe). Al recibir un estado final (SUCCESS/FAILED/COMPLETED), la middleware actualiza el estado en Affilentra.
- Realice reconciliaciones periódicas: contraste la exportación de Affilentra, los informes del proveedor y los extractos bancarios; registre y alerte sobre las diferencias.
Generación automatizada de justificantes contables
Los justificantes automatizados son requisito para una contabilidad auditablemente segura. Procedimiento:
- Genere por cada pago un justificante en PDF con los siguientes datos: payout_id, partner_id, nombre/dirección del partner, bruto/neto/comisiones, divisa, referencia de pago del proveedor, timestamp.
- Adjunte además el recibo del proveedor (descarga por API de PayPal/Stripe/Wise) como anexo al Payout en Affilentra o guárdelo en el sistema contable.
- Formatos de exportación: CSV para importes masivos, PDF para justificantes individuales, opcionalmente XML/compatible con DATEV según el sistema contable destino.
Gestión de errores, idempotencia y operación
- Idempotencia: use claves únicas en el proveedor (p. ej. payout_id como sender_batch_id) para evitar pagos duplicados.
- Reintentos: implemente estrategias de backoff ante errores temporales y una cola de revisión manual si persisten los errores.
- Monitorización y alertas: registre los payloads de webhook, las respuestas del proveedor y las diferencias en la conciliación; configure alertas ante desviaciones.
- Pruebas en sandbox: realice integraciones de comprobación en el modo Sandbox de los tres proveedores antes de poner en marcha en producción.
Caso práctico: flujo de una devolución de pago (descripción breve)
1) Affilentra genera una exportación de Payout y lanza payout_exported a su middleware. 2) La middleware valida, mapea campos y llama a la API del proveedor. 3) El proveedor confirma con una referencia → la middleware actualiza Affilentra con status=sent y provider_reference. 4) El proveedor envía el webhook final (p. ej. completed) → la middleware marca status=reconciled, deduce comisiones y crea un comprobante en PDF que se adjunta a Affilentra.
Conclusión y siguiente paso
La integración técnica de los payouts de Affilentra con PayPal, Wise y Stripe Connect mediante webhooks es un proceso claramente estructurado: exportación limpia, entrega segura del webhook, middleware con mapeo al proveedor, retroalimentación de estado fiable y generación automática de comprobantes. Así, los comerciantes mantienen el control sobre las condiciones y la trazabilidad, mientras los socios disponen de historiales de pago transparentes.
Actúe ahora: Elija un inicio: discuta sus requisitos y el entorno de pruebas con el equipo de Affilentra y comience la integración. Más información y contacto: https://affilentra.de
Siguiente paso
Probar Affilentra usted mismo
Plataforma unificada que reúne de forma transparente la puesta a disposición de productos, el tracking, la validación de conversiones, el cálculo de comisiones y el pago con roles claramente diferenciados; opción de instalación self-hosted con licencia perpetua sin participación en ingresos; los comerciantes conservan el control sobre productos, condiciones y material promocional; los socios reciben enlaces de seguimiento personales y un historial de pagos verificable.