Intégration API PayPal
Nous développons votre connecteur PayPal
Votre application appelle l'API PayPal pour encaisser, gérer les abonnements et traiter les litiges sans saisie de carte côté acheteur.
- Équipe produit senior
- intégrations de paiement en production
- du cadrage au monitoring
À quoi sert l'API PayPal et pourquoi l'intégrer comme moyen de paiement ?
PayPal est le portefeuille numérique le plus utilisé dans le monde, particulièrement apprécié des acheteurs en ligne pour sa simplicité et la protection qu'il offre. Son API permet à votre application de prendre un paiement ponctuel, de gérer des abonnements, de déclencher un remboursement et d'être notifié de chaque événement de paiement. On l'intègre pour proposer PayPal en complément de la carte bancaire dans un tunnel de commande, ou pour encaisser sur des marchés où PayPal est le moyen de paiement dominant. C'est aussi la solution de référence pour gérer les litiges acheteur directement depuis votre back-office.
Ce que nos clients construisent sur l'API PayPal
Checkout e-commerce avec capture réelle
Le retour navigateur n'ouvre pas la commande. C'est PAYMENT.CAPTURE.COMPLETED qui déclenche l'expédition, pas un callback de page.
Abonnement SaaS piloté par les événements
Activation, suspension et échec de paiement ferment ou rouvrent l'accès. Plus de booléen maintenu à la main dans deux systèmes.
File de litiges dans le back-office
CUSTOMER.DISPUTE.CREATED alimente une file avec délai et pièces, au lieu d'un e-mail découvert trop tard.
Encaissement pour plusieurs marchands
PayPal-Auth-Assertion permet d'agir pour un marchand sans un jeton par compte, avec le code BN d'attribution partenaire.
Ce que ça change dans votre encaissement
La technique au service d'un résultat mesurable : moins d'abandons, des accès justes, des litiges traités.
Moins d'abandons au paiement
L'acheteur paie avec un compte qu'il a déjà. Pas de saisie des 16 chiffres sur mobile, souvent l'étape qui fait fermer le panier.
Un accès aligné sur le paiement
L'abonnement PayPal ouvre, suspend et ferme le droit d'accès. Vous arrêtez de recouper un export et un tableau interne.
Les litiges sortent du support
Chaque contestation arrive dans votre outil, avec un délai. Vous répondez dans les temps au lieu de le découvrir au débit.
Une comptabilité qui retombe juste
Encaissements et remboursements portent une référence de commande. Le lettrage cesse d'être un export relu à la main.
Comment nous livrons votre connecteur PayPal
Cadrage
Checkout, abonnement ou plateforme, règle 3DS, événements utiles. On tranche le modèle avant d'écrire une ligne de code.
Développement
Connecteur typé, vérification RSA sur le corps brut, PayPal-Request-Id dérivé de l'intention métier, file de reprise.
Recette
PayPal-Mock-Response pour les erreurs métier, bac à sable pour la signature, simulateur seulement pour la réception.
Monitoring
Alertes sur événement non traité, journal des captures, tableau de bord de santé. Vous savez qu'un flux est cassé avant vos clients.
Ce que permet l'API PayPal
- Orders et capture
- Création d'une commande, approbation par l'acheteur, capture. L'état métier se lit sur la capture, pas sur le retour navigateur.
- Abonnements et plans
- Plans, activation, suspension, réactivation, expiration et échec de paiement. Chaque transition est un événement nommé.
- Litiges et remboursements
- Ouverture d'une file sur CUSTOMER.DISPUTE.CREATED, remboursement d'une capture avec PayPal-Request-Id pour éviter le double avoir.
- Webhooks et 3DS
- Jusqu'à 10 URL par application, SCA_WHEN_REQUIRED ou SCA_ALWAYS, et liability_shift comme règle de capture, pas comme champ oublié.
Le vocabulaire de l'API PayPal
- PayPal-Request-Id
- En-tête d'idempotence sur certains POST, mémorisé jusqu'à 45 jours sur l'exemple du remboursement. Il n'est pas universel : la référence API le dit endpoint par endpoint.
- paypal-transmission-sig
- Signature Base64 du webhook. Le message signé est transmissionId | timeStamp | webhookId | crc32, où crc32 est le CRC32 du corps brut en décimal, vérifié en SHA256withRSA.
- webhookId
- Identifiant de l'abonnement, ni dans l'en-tête ni dans le corps. Sans l'avoir persisté à la création de l'URL, la vérification de signature est impossible.
- liability_shift
- Résultat 3DS qui dit si le risque de contestation a basculé sur l'émetteur. C'est une règle métier (capturer ou non), pas un détail technique à ignorer.
- PayPal-Auth-Assertion
- JWT qui identifie le marchand pour lequel on agit. PayPal recommande payer_id plutôt que l'e-mail, et un JWT non signé (alg none) pour ce cas.
- SCA_WHEN_REQUIRED
- Valeur par défaut de verification.method : PayPal déclenche 3DS seulement quand la réglementation locale l'impose. SCA_ALWAYS le tente à chaque carte.
Les contraintes réelles de l'API PayPal
La signature n'est pas un HMAC
On reconstruit transmissionId|timeStamp|webhookId|crc32 sur le corps brut, CRC32 en décimal, puis RSA-SHA256 avec le certificat de paypal-cert-url. Parser puis re-sérialiser casse la vérification.
Le simulateur ne vérifie rien
Sur les événements simulés, l'identifiant vaut la chaîne WEBHOOK_ID, et POST /v1/notifications/verify-webhook-signature n'est pas supporté. Beaucoup d'équipes croient leur code cassé.
Jusqu'à 25 retentatives, 3 jours
Sans 2xx, PayPal retente jusqu'à 25 fois sur 3 jours, puis passe en Failed. Un endpoint cassé un week-end produit des doublons à dédupliquer, pas une perte silencieuse.
Idempotence et débit à mesurer
PayPal-Request-Id n'est pas disponible partout. Aucune limite de débit chiffrée n'est publiée : un débit de traitement se mesure en test, puis se surveille, il ne se déduit pas d'une doc.
Orders ou Subscriptions ?
Deux APIs pour deux questions. Le bon choix dépend du cycle de vie de l'argent, pas du logo sur le bouton.
| Critère | OrdersPaiement ponctuel | SubscriptionsRécurrent |
|---|---|---|
| Objet métier | Une commande, puis une capture | Un plan, puis un abonnement |
| Événement qui clôt | PAYMENT.CAPTURE.COMPLETED | BILLING.SUBSCRIPTION.ACTIVATED |
| Échec suivant | Refus ou capture denied | BILLING.SUBSCRIPTION.PAYMENT.FAILED |
| Accès produit | Ouvert à la capture | Ouvert, suspendu, rouvert sur événements |
| Héritage à éviter | Ancien champ 3DS déprécié | Billing Agreements, déprécié |
| Cas plateforme | PayPal-Auth-Assertion, code BN | Même en-tête, cycle d'abonnement en plus |
| Le bon cas | Panier, commande, prestation unique | SaaS, cotisation, accès dans le temps |
Les deux se combinent : un premier Orders pour l'inscription, puis Subscriptions pour le renouvellement. C'est un arbitrage de cadrage, pas un choix définitif.
Ce que nous mesurons sur une intégration PayPal
Les autres API de paiement
Si PayPal n'est pas le bon choix pour votre modèle, ces options se discutent au cadrage.
PayPalNous développons votre connecteur PayPalCette page
StripeLe plus complet : Connect, Billing, entitlements, quand le paiement est le cœur du produit.
SumUpL'encaissement en présence, quand la vente se conclut sur un terminal.
GoCardlessLe prélèvement SEPA récurrent, sans carte qui expire sur les montants B2B.
MollieNous développons votre connecteur MollieOn combine PayPal avec
La stack qui entoure PayPal sur nos projets.
Intégration PayPal : vos questions
Trois étapes. D'abord obtenir un jeton via POST /v1/oauth2/token en client_credentials, et lire les scopes réellement ouverts avant le premier appel métier. Ensuite construire le connecteur côté serveur : création d'Orders ou de Subscriptions, avec PayPal-Request-Id dérivé de l'intention métier sur les POST qui le supportent. Enfin traiter les webhooks : persister le webhookId à la création de l'URL, vérifier la signature RSA sur le corps brut (CRC32 en décimal), répondre 200, traiter en file. La partie sensible n'est pas l'appel API, c'est la vérification qui n'est pas un HMAC, et le fait que PayPal retente jusqu'à 25 fois sur 3 jours.
Cela dépend du modèle : un checkout Orders avec capture est plus court qu'un abonnement avec ouverture d'accès, file de litiges et cas plateforme. La difficulté n'est presque jamais le bouton PayPal, elle est dans la signature RSA, le simulateur qui ne vérifie pas, et les doublons de webhook. Un premier flux utile se livre en deux à trois semaines. Une chaîne complète avec abonnements et litiges demande plutôt six à huit semaines. Nous cadrons le périmètre en amont et donnons une estimation ferme avant de commencer.
Orders encaisse une commande : création, approbation, capture. L'événement qui clôt le flux est PAYMENT.CAPTURE.COMPLETED. Subscriptions gère un cycle dans le temps : plan, activation, suspension, échec de paiement, avec des événements BILLING.SUBSCRIPTION.*. Les Billing Agreements REST sont dépréciés au profit de Subscriptions. Beaucoup de projets ont besoin des deux : un premier paiement Orders, puis un abonnement. Le modèle de données doit être pensé pour les deux dès le cadrage, pas raccordé après coup.
Pas par HMAC, contrairement à Stripe ou GoCardless. On reconstruit transmissionId|timeStamp|webhookId|crc32, où crc32 est le CRC32 du corps HTTP brut exprimé en décimal. La signature paypal-transmission-sig se vérifie en SHA256withRSA avec le certificat téléchargé depuis paypal-cert-url, après contrôle de l'hôte. Le webhookId vient de la configuration de l'abonnement, pas du message. Le simulateur n'est pas vérifiable par POST /v1/notifications/verify-webhook-signature : pour tester la crypto, il faut un événement réel de bac à sable. Sous Express ou NestJS, la route webhook a besoin du corps brut, pas d'un JSON re-sérialisé.
Oui, et c'est une demande fréquente. Nous construisons le flux qui pousse captures et remboursements avec la référence de commande (supplementary_data.related_ids.order_id sur la capture), puis un contrôle de cohérence périodique entre ce que PayPal expose et ce que votre comptabilité enregistre, avec alerte sur écart plutôt que correction silencieuse. Une écriture comptable ne se répare pas dans le dos du comptable. Le lettrage manuel d'un export PayPal disparaît dès que la référence est portée de bout en bout.
Un projet d'intégration PayPal ?
Parlons-en. 30 minutes pour cadrer votre checkout ou vos abonnements, vérifier ce que l'API permet vraiment et vous dire franchement ce qui est faisable.
Parler de mon projet PayPal