Comment intégrer l'API PayPal ?

PayPal est l'une des plateformes de paiement les plus utilisées au monde, et des millions d'entreprises s'en servent pour se faire payer, envoyer des factures et suivre leur trésorerie. Si votre logiciel s'adresse à ces entreprises, une connexion à PayPal vous permet de :

• Récupérer automatiquement les factures, leur statut et le détail des lignes
• Extraire les données de paiement et de solde pour le rapprochement et le reporting
• Accéder aux données produits et catalogue liées aux factures
• Réduire la saisie manuelle et les erreurs pour vos utilisateurs

Ce guide explique le fonctionnement de l'API PayPal, les cas d'usage qu'elle ouvre, comment la configurer et les bonnes pratiques à connaître. Et comme PayPal est disponible à la fois dans l'API Paiement unifiée et l'API Facturation unifiée de Chift, nous vous montrons aussi comment vous épargner le plus gros du travail.

Qu'est-ce que l'API PayPal ?

PayPal expose une API REST qui renvoie du JSON et utilise les méthodes HTTP standard. Il s'agit en réalité d'un ensemble d'API organisées par domaine. Pour les cas d'usage de facturation et de paiement, les plus importantes sont :

• Invoicing API (v2) (/v2/invoicing/), pour rechercher, créer et récupérer des factures. À noter : lister les factures passe par un endpoint de recherche en POST (/v2/invoicing/search-invoices) plutôt que par un GET classique, un choix de conception inhabituel.
• Catalog Products API (v1) (/v1/catalogs/products), pour récupérer les données produits et catalogue.
• Reporting API (v1) (/v1/reporting/balances), utilisée pour tester la connexion via une vérification de solde.
• OAuth2 API (v1) (/v1/oauth2/token), qui gère l'authentification.

L'authentification repose sur un flux pseudo-OAuth2. Vous vous authentifiez avec votre client_id et votre client_secret en HTTP Basic Auth pour obtenir un token Bearer. Il n'y a pas de redirection d'autorisation côté utilisateur, c'est donc essentiellement un flux Client Credentials. PayPal propose par ailleurs deux environnements, Sandbox et Production, au comportement identique et qui ne diffèrent que par l'URL de base.

Les données accessibles comprennent les factures (avec leurs statuts, montants et lignes), les paiements, les données catalogue et les soldes de compte. La recherche de factures accepte des filtres par plage de dates et par statut, avec une pagination par page pouvant aller jusqu'à 100 éléments.

Documentation officielle : developer.paypal.com

{{CTA-1}}

Exemples de cas d'usage de l'intégration API PayPal

Se connecter à PayPal ouvre des automatisations concrètes pour tout produit qui manipule des données financières. Voici comment des éditeurs de logiciels exploitent les données de factures et de paiements PayPal grâce à Chift.

Accélérer les décisions de crédit grâce aux données de factures et de paiements

Les organismes de prêt aux entreprises peuvent récupérer les factures ouvertes, l'historique des paiements et les montants en attente pour évaluer la santé financière d'une société en temps réel. Des données plus riches, ce sont des décisions de crédit plus rapides et mieux informées, avec une réponse d'éligibilité en moins d'une minute.

Pour en savoir plus, consultez l'étude de cas Defacto.

Développer la connectivité paiement et facturation des plateformes de pré-comptabilité

Des plateformes de pré-comptabilité comme Inqom se connectent à PayPal en même temps qu'à des dizaines d'autres outils pour centraliser leurs données de paiement et de facturation. Une seule intégration à Chift leur permet d'ajouter de nouvelles sources rapidement, sans construire ni maintenir chaque connexion une par une.

Découvrez l'étude de cas : Comment Inqom développe très vite sa connectivité POS, Facturation et Paiement avec Chift.

Suivi et prévision de trésorerie

Les outils de gestion de trésorerie peuvent récupérer les factures ouvertes et le statut des paiements dans PayPal pour bâtir une vision précise et prospective de la position de trésorerie d'une entreprise. Dès qu'un paiement arrive, la prévision se met à jour, et vos utilisateurs voient toujours ce qui entre réellement.

Pour plus d'exemples de la façon dont les intégrations de paiement et de facturation peuvent améliorer votre produit, explorez nos études de cas Chift.

Configurer votre intégration API PayPal

Se lancer avec PayPal ne demande que quelques étapes :

1. Créez un compte PayPal Developer et ouvrez le PayPal Developer Dashboard.
2. Créez une App dans « Apps & Credentials ». Cela génère votre client_id et votre client_secret.
3. Activez la fonctionnalité Invoicing pour votre app dans le dashboard. Sans elle, l'API renvoie des erreurs de permission 406.
4. Choisissez votre environnement : Sandbox pour les tests, Production pour les données réelles.
5. Renseignez les identifiants (client_id, client_secret et environnement) dans votre configuration de connexion Chift. Chift gère la génération et le renouvellement des tokens pour vous.

Aucune configuration de webhook n'est nécessaire pour l'intégration actuelle. Les données sont récupérées à la demande, via polling et mise en cache.

L'API elle-même est accessible aux développeurs, mais une intégration prête pour la production demande plus qu'un premier appel réussi. Il faut une normalisation cohérente des données, le renouvellement des tokens, la gestion des erreurs et le multi-tenant pour chacun de vos utilisateurs. C'est cette partie qui grignote discrètement le temps de vos équipes, et c'est précisément là que Chift intervient.

Bonnes pratiques pour l'intégration API PayPal

Quelques points à bien maîtriser dès le départ :

• Développez d'abord en Sandbox. PayPal fournit un environnement de test complet avec des comptes de test. Passez en Production seulement au moment de la mise en ligne, seule l'URL de base change.
• Gérez soigneusement l'endpoint de recherche. Lister les factures implique un POST vers /v2/invoicing/search-invoices avec les filtres dans le corps de la requête, et non un simple GET. Passez toujours total_required=true et total_count_required=true en paramètres pour obtenir une pagination fiable.
• Anticipez les statuts de facture. Les factures PayPal portent de nombreux statuts (DRAFT, SENT, SCHEDULED, PAID, UNPAID, PARTIALLY_PAID, CANCELLED, REFUNDED, et d'autres). Filtrer sur un statut de paiement demande souvent d'interroger plusieurs combinaisons de statuts, un simple filtre « unpaid » peut nécessiter deux appels distincts couvrant des groupes de statuts différents.
• Récupérez les lignes une par une. L'endpoint de recherche renvoie des résumés de factures, sans le détail des lignes. Pour obtenir les données complètes (lignes, montants, paiements), appelez GET /v2/invoicing/invoices/{id} pour chaque facture. Tenez-en compte dans l'estimation de votre consommation d'API.
• Vérifiez les permissions de votre app. Une erreur 406 signifie presque toujours que la fonctionnalité Invoicing n'est pas activée dans « Apps & Credentials », et non que la requête est mal formée.
• Respectez les limites de débit. Restez sous environ 30 requêtes par seconde, et ajoutez un backoff exponentiel et de la mise en cache pour les volumes élevés, surtout autour de l'endpoint de recherche.

Connectez-vous à PayPal, Stripe, Mollie et bien d'autres avec une seule intégration

Construire une connexion directe à PayPal demande du temps, des efforts et une maintenance continue, surtout dès que vous devez aussi prendre en charge les autres outils de paiement et de facturation utilisés par vos clients.

Avec l'API Paiement unifiée et l'API Facturation unifiée de Chift, vous vous connectez une seule fois et accédez à PayPal, Stripe, Payplug, Mollie, Axonaut, Qonto, Sellsy et bien d'autres, via un modèle de données unique et cohérent.

• Une seule intégration pour des dizaines d'outils de paiement et de facturation
• Authentification, pagination et limites de débit gérées d'office
• Des données unifiées et standardisées
• Synchronisation à la demande avec mise en cache et monitoring avancé
• Une expérience fluide pour vos utilisateurs

Réserver une démo →

FAQ API PayPal

Quels endpoints sont inclus dans l'API PayPal ?

Via Chift, PayPal est disponible dans l'API Paiement unifiée et l'API Facturation unifiée, avec un ensemble d'endpoints standardisés, parmi lesquels (sans s'y limiter) :

• Factures /invoices
• Paiements /payments
• Produits /products
• Soldes /balances

Consultez notre documentation de l'API PayPal pour la liste complète des routes disponibles.

Quelles sont les limites de débit de l'API PayPal ?

PayPal ne publie pas de limites de débit détaillées par endpoint. La limitation s'applique par app et varie selon l'endpoint et l'historique du compte. L'Invoicing API est connue pour être plus restrictive : un excès d'appels vers l'endpoint de recherche peut déclencher des réponses HTTP 429 (Too Many Requests). En règle générale, restez sous environ 30 requêtes par seconde, et utilisez un backoff exponentiel ainsi que de la mise en cache pour les charges élevées. Le connecteur Chift s'en charge pour vous grâce à sa couche de cache. Vous pouvez consulter les recommandations de PayPal dans leur référence sur le rate limiting.

Comment obtenir mes identifiants API PayPal ?

En version courte :

1. Rendez-vous sur le PayPal Developer Dashboard et connectez-vous avec votre compte PayPal Business (ou créez-en un).
2. Ouvrez Apps & Credentials et basculez entre Sandbox et Live selon vos besoins.
3. Cliquez sur Create App, donnez-lui un nom et sélectionnez le compte sandbox associé.
4. Copiez votre Client ID (visible) et votre Secret (cliquez sur « Show » pour l'afficher).
5. Dans les paramètres de fonctionnalités de l'app, vérifiez que Invoicing est activé.

Ce sont les identifiants à renseigner dans votre connexion Chift. Nous détaillerons bientôt tout le processus dans un guide dédié.