Pourquoi les intégrations de paiements pilotées par webhook sont importantes
Les commerçants qui versent automatiquement des commissions aux partenaires réduisent le travail manuel, évitent les erreurs et accélèrent les règlements. Affilentra fournit des exports de paiement et des webhooks comme points de transfert. En pratique, une petite couche d'intégration‑middleware est nécessaire pour recevoir les données d'export, les transmettre aux prestataires de paiement externes (PayPal Payouts, Wise, Stripe Connect), renvoyer les changements de statut et générer des justificatifs comptables. Cet article indique précisément quelles configurations et quelles étapes sont requises.
Aperçu : architecture et responsabilités
- Affilentra : génère les exports de paiements et déclenche les événements webhook avec les ensembles de paiements.
- Middleware (votre système ou un petit service connecteur) : valide le webhook, mappe les champs, appelle les API des prestataires, traite les callbacks des prestataires, crée des justificatifs et écrit les statuts dans Affilentra.
- Prestataires de paiement (PayPal, Wise, Stripe Connect) : exécutent les paiements et fournissent des références de paiement / webhooks pour le statut final.
Prérequis avant l'intégration
- Installation Affilentra (self‑hosted) avec système de webhook et fonction d'export activés. SSL pour le endpoint webhook.
- Compte et identifiants API chez les prestataires cibles (accès sandbox pour les tests).
- Middleware avec endpoint HTTPS, stockage persistant (BD), et capacité à générer des fichiers/PDF et à les attacher à Affilentra.
Étape 1 : définir proprement l'export de paiement dans Affilentra
Configurez dans Affilentra un export de paiements qui fournisse tous les champs nécessaires. Format recommandé : JSON ou CSV en UTF‑8. Champs importants :
- payout_id (ID interne unique)
- partner_id / partner_identifier
- payee_type (email | iban | account_id)
- payee_address (E‑mail, IBAN, ID de compte bancaire)
- amount (décimal, p. ex. 123.45)
- currency (code ISO, p. ex. EUR)
- gross / net / fee (si des montants séparés doivent être indiqués)
- description / reference
Important : prévoyez un champ pour une référence externe (provider_reference) et un champ de statut (pending / sent / failed / reconciled) — la middleware les remplira.
Étape 2 : configurer le webhook dans Affilentra
- Créez un endpoint webhook dans Affilentra qui envoie un événement lors de l'exécution d'un export de paiements (p. ex. payout_exported).
- Sécurisez l'événement webhook avec une signature HMAC (secret partagé). La middleware vérifie cette signature par rapport aux payloads reçus.
- Configurez des tentatives de réessai dans Affilentra (p. ex. 3 tentatives avec backoff exponentiel) et consignez les messages d'erreur dans des logs.
Étape 3 : Middleware – flux et points d'implémentation
La middleware est l'élément central. Tâches principales :
- Validation des webhooks (signature, schéma, vérification des doublons).
- Mapping : convertir l'export Affilentra en charge utile du prestataire.
- Appel au prestataire : créer des lots, définir des idempotency‑keys, gérer les erreurs d'API.
- Gestion des statuts : traiter les réponses du prestataire, renvoyer le statut à Affilentra.
- Génération des justificatifs : produire PDF/CSV/JSON, lier au paiement et transmettre à la comptabilité.
Exemples de mapping (orientés pratique)
- PayPal : mapper payee_address → receiver_email, amount + currency → amount, utiliser sender_batch_id = payout_id.
- Wise : si un IBAN est présent, créer le Recipient, générer une Quote (en cas de conversion de devise) et effectuer le Transfer avec reference = payout_id.
- Stripe Connect : pour les comptes connectés, utilisez le paramètre destination ou envoyez des Payouts au nom du Connected Account ; effectuez éventuellement d'abord un Transfer.
Spécificités des prestataires & conseils
- PayPal Payouts : utilisez des batchs de payouts pour l'efficacité ; définissez sender_batch_id pour l'idempotence ; conservez payout_item_id et batch_status pour la réconciliation ultérieure.
- Wise : créez le recipient une fois et réutilisez la recipient_id ; prenez en compte l'étape de Quote possible lors de la conversion de devise.
- Stripe Connect : vérifiez si votre flux doit utiliser des Transfers vers des comptes connectés ou des virements bancaires externes ; utilisez des Idempotency‑Keys et consultez les balance_transfers.
Retour de statut à Affilentra et réconciliation
Voici comment garantir des cycles d'enregistrement fiables :
- Immédiatement après la réponse du prestataire : mettez à jour les payouts Affilentra avec provider_reference, status = sent (ou failed) et les informations de frais.
- Implémentez un listener pour les webhooks des prestataires (par ex. webhooks PayPal/Stripe). À la réception d'un statut final (SUCCESS/FAILED/COMPLETED), le middleware met à jour le statut dans Affilentra.
- Effectuez des réconciliations régulières : rapprochement de l'export Affilentra, des rapports du prestataire et des relevés bancaires ; consignez et alertez les écarts.
Génération automatisée des justificatifs comptables
Les justificatifs automatisés sont une condition pour une comptabilité vérifiable. Procédure :
- Générez par paiement un justificatif PDF contenant : payout_id, partner_id, nom/adresse du partenaire, brut/net/frais, devise, référence de paiement du prestataire, horodatage.
- Joignez en outre le reçu du prestataire (téléchargement API de PayPal/Stripe/Wise) en tant que pièce jointe au payout dans Affilentra ou stockez‑le dans le système comptable.
- Formats d'export : CSV pour les imports massifs, PDF pour les justificatifs individuels, éventuellement XML/compatible DATEV selon la comptabilité cible.
Gestion des erreurs, idempotence et exploitation
- Idempotence : Utilisez des clés uniques côté fournisseur (p. ex. payout_id comme sender_batch_id) pour éviter les paiements en double.
- Retries : Mettez en place des stratégies de backoff pour les erreurs temporaires et une file de revue manuelle en cas d'erreurs persistantes.
- Monitoring & Alerting : Enregistrez les payloads des webhooks, les réponses des fournisseurs et les différences de réconciliation ; configurez des alertes en cas d'écarts.
- Tests en sandbox : Effectuez des runs d'intégration en mode sandbox avec les trois fournisseurs avant de lancer la production.
Cas pratique : déroulé d'une payout (description courte)
1) Affilentra génère un export de payout et déclenche payout_exported vers votre middleware. 2) Le middleware valide, mappe les champs et appelle l'API du fournisseur. 3) Le fournisseur confirme avec une référence → le middleware met à jour Affilentra avec status=sent et provider_reference. 4) Le fournisseur envoie le webhook final (p. ex. completed) → le middleware passe à status=reconciled, prélève les frais et crée un justificatif PDF qui est attaché à Affilentra.
Conclusion et prochaine étape
L'intégration technique des payouts Affilentra avec PayPal, Wise et Stripe Connect via webhooks est un processus clairement structuré : export propre, transmission sécurisée des webhooks, middleware avec mapping fournisseur, retour d'état fiable et génération automatique des justificatifs. Ainsi, les marchands conservent le contrôle des conditions et de la traçabilité, tandis que les partenaires obtiennent un historique de paiements transparent.
Agissez maintenant : Choisissez un point d'entrée : discutez de vos besoins et de votre environnement de test avec l'équipe Affilentra et lancez l'intégration. Plus d'informations et contact : https://affilentra.de
Prochaine étape
Essayer Affilentra soi‑même
Plateforme unifiée qui rassemble de manière transparente la mise en ligne des produits, le tracking, la validation des conversions, le calcul des commissions et le paiement selon des rôles clairement séparés ; option d'installation self-hosted avec licence perpétuelle sans partage de chiffre d'affaires ; les marchands conservent le contrôle des produits, des conditions et des supports publicitaires ; les partenaires reçoivent des liens de tracking personnels et un historique de paiements traçable.