Brancher PayPal sur votre logiciel : commandes, captures et litiges

Que faut-il avant la première ligne de code ?

Il faut un compte développeur PayPal, une application REST et, pour la production, un compte PayPal Business.

1. Créer l'application dans le tableau de bord développeur, rubrique Apps & Credentials : PayPal fournit un identifiant client (client ID) et un secret, à garder confidentiel.
2. Obtenir un jeton : le logiciel envoie l'identifiant et le secret à /v1/oauth2/token avec grant_type=client_credentials, et reçoit un jeton Bearer dont la durée de validité, en secondes, figure dans la réponse.
3. Tester dans le bac à sable : l'adresse https://api-m.sandbox.paypal.com remplace https://api-m.paypal.com, et deux comptes fictifs sont fournis par défaut, un acheteur et un vendeur.
4. Passer en production avec les identifiants de l'application live.

PayPal recommande de garder le jeton en cache et de le réutiliser jusqu'à son expiration, au lieu d'en demander un nouveau à chaque requête.

Quelle API PayPal pour quel besoin de gestion ?

PayPal découpe son offre en plusieurs API REST. Celles qui intéressent un logiciel de gestion, d'après la documentation consultée en octobre 2026 :

Autoriser, capturer, rembourser : les délais imposés par PayPal

Une commande PayPal peut être capturée tout de suite ou seulement autorisée, la capture venant plus tard. L'API Payments v2 encadre l'autorisation par des délais précis :

• une période de garantie (honor period) de 3 jours suit l'autorisation ; la réautorisation, qui vérifie que les fonds sont toujours disponibles, n'est possible qu'après cette période ;
• la réautorisation se fait dans la période d'autorisation de 29 jours, du 4e au 29e jour après l'autorisation d'origine ; la référence de l'API est ambiguë sur le nombre de réautorisations admises, un point à tester dans le bac à sable ;
• passé 30 jours après l'autorisation d'origine, il faut créer un nouveau paiement autorisé, et l'événement PAYMENT.AUTHORIZATION.VOIDED signale l'autorisation expirée ;
• une autorisation entièrement capturée ne peut plus être annulée.

Pour les remboursements, un corps de requête vide rembourse toute la capture et un objet amount en rembourse une partie. Le montant ne peut pas dépasser ce qui reste à rembourser (erreur REFUND_AMOUNT_EXCEEDED), et PayPal applique une limite de temps dont la référence ne donne pas la durée (erreur REFUND_TIME_LIMIT_EXCEEDED). Un logiciel de service après-vente affiche ces refus à l'opérateur au lieu de les laisser dormir dans un journal.

Webhooks PayPal : abonnement, signature et réessais

Une application PayPal peut abonner jusqu'à 10 adresses de webhook, chacune à une liste d'événements ou à tous. Pour un logiciel de gestion, les événements de paiement les plus utiles sont les suivants.

Pour s'assurer qu'un message vient bien de PayPal, la documentation propose deux méthodes : calculer le CRC32 du message et vérifier sa signature localement, ou renvoyer le message, l'identifiant du webhook et les en-têtes PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-TIME, PAYPAL-TRANSMISSION-SIG, PAYPAL-CERT-URL et PAYPAL-AUTH-ALGO à l'endpoint /v1/notifications/verify-webhook-signature, qui répond SUCCESS ou FAILURE.

Tant que le serveur ne répond pas par un code 2xx, PayPal réessaie jusqu'à 25 fois sur 3 jours. Au-delà, la livraison est marquée Failed et ne repart que sur demande : depuis le tableau de bord des événements de webhook, ou par l'endpoint de l'API Webhooks qui renvoie une notification à partir de son identifiant. Une relecture planifiée des commandes reste donc indispensable.

Quatre usages de PayPal dans un logiciel de gestion

• La commande payée qui crée la facture. Le logiciel crée une commande Orders v2 avec son propre numéro de facture ; le client approuve, le logiciel capture, puis PAYMENT.CAPTURE.COMPLETED déclenche la facture et la préparation. Si le compte exige un numéro de facture unique, une seconde commande portant le même numéro est refusée (DUPLICATE_INVOICE_ID), ce qui bloque un double encaissement.
• Le matériel expédié plus tard. Pour une fabrication à la commande, le logiciel autorise à la commande et capture à l'expédition, dans les délais décrits plus haut, puis ajoute le numéro de suivi à la commande PayPal.
• Le litige client. L'API Disputes liste les litiges et leur échéance de réponse (seller_response_due_date). Le logiciel joint la preuve d'expédition (PROOF_OF_FULFILLMENT, avec le suivi du colis) ou celle d'un remboursement déjà fait. Selon PayPal, la phase d'enquête dure jusqu'à 20 jours, sauf si le litige passe au stade de la réclamation.
• La clôture mensuelle. La recherche de transactions couvre les trois dernières années, mais une transaction peut mettre jusqu'à trois heures à y apparaître : le rapprochement nocturne porte donc sur la veille.

Pour un client facturé chaque mois, deux voies existent : l'API Subscriptions, où PayPal génère les échéances d'un plan, ou l'enregistrement du moyen de paiement par l'API Payment Method Tokens, que PayPal présente pour la facturation d'abonnements, l'essai gratuit et l'accélération des paiements suivants. Ce second service est ouvert dans 35 pays, dont la France ; pour les cartes, il suppose une intégration Expanded Checkout et une conformité PCI SAQ D.

Erreurs, limites et doublons : ce que PayPal laisse à votre charge

PayPal ne publie pas de limites d'appels chiffrées, car elles varient selon l'API, l'environnement et le contexte. Un dépassement renvoie une erreur 429 ; la documentation conseille d'espacer les nouvelles tentatives de façon croissante, de regrouper les requêtes et de préférer les webhooks à l'interrogation en boucle.

Pour rejouer un POST sans risque après une coupure réseau ou une erreur 500, le logiciel envoie un identifiant unique dans l'en-tête PayPal-Request-Id : tant que PayPal conserve cet identifiant, la requête répétée ne crée pas d'opération en double. Pour la recette, l'en-tête PayPal-Mock-Response simule des erreurs précises, ce qui évite d'attendre qu'un cas rare se produise.

Les données d'acheteurs que le logiciel conserve à partir des réponses PayPal entrent dans votre registre de traitements : notre guide RGPD et logiciel métier rappelle les obligations, et notre guide sécuriser une application métier traite de la garde du secret de l'application.

Bouton PayPal de votre plateforme ou intégration développée ?

Si votre site tourne sur une plateforme e-commerce qui propose déjà PayPal, commencez par activer ce moyen de paiement : l'encaissement en ligne est alors couvert sans développement. Une intégration développée se justifie quand PayPal doit dialoguer avec un logiciel de gestion : capture pilotée par l'expédition, litiges traités depuis le service client, rapprochement automatique, abonnements dont les règles vivent dans votre outil. Pour comparer les prestataires, nos pages intégration Stripe et intégration Mollie posent les mêmes questions.

Chez YMHB Web, le cadrage fixe d'abord les API utilisées, les événements écoutés, les statuts correspondants dans votre logiciel et le traitement des litiges ; le chiffrage suit. L'intégration est développée dans le bac à sable PayPal avec l'application de votre compte, puis basculée en production. Vous recevez :

• un point de réception qui vérifie chaque signature de webhook avant d'agir ;
• un PayPal-Request-Id sur chaque création et une relecture planifiée des commandes restées sans réponse ;
• un journal des échanges et un écran des opérations en anomalie ;
• le code, déposé chez vous et documenté, et des identifiants qui restent au nom de votre entreprise.

Le principe général est décrit sur notre page connecter ses logiciels par API.