Aperçu : OAuth REST PayPal moderne vs anciennes signatures API NVP
Lors de l'intégration de PayPal dans Passinstance pour monétiser des passes numériques, billets d'événements ou cartes de membre via PassFlow, les commerçants demandent souvent comment obtenir une « signature API PayPal ».
Dans l'ancien écosystème PayPal, l'API classique NVP/SOAP (Name-Value Pair) reposait sur un jeu de 3 identifiants : un API Username, un API Password et une API Signature. Toutefois, les systèmes e-commerce modernes, les applications de portefeuille mobile et Passinstance s'appuient sur l'API REST PayPal v2 alimentée par OAuth 2.0 :
| Modèle d'identifiants | Architecture | Composants | Prise en charge & sécurité |
|---|---|---|---|
| API REST PayPal moderne (Obligatoire) | Identifiants client OAuth 2.0 | Client ID & Client Secret | Pris en charge : stockés de manière sécurisée au niveau de l'espace de travail, compatibles Smart Payment Buttons, Venmo, Paiement en 4X et webhooks temps réel. |
| Ancienne API PayPal NVP / SOAP | Authentification classique à 3 jetons | API Username, API Password, API Signature | Obsolète : les écritures directes d'identifiants au niveau formulaire sont bloquées par rejectLegacySecretWrites dans l'API Passinstance. |
Pourquoi l'écriture d'anciens secrets est bloquée (rejectLegacySecretWrites)
Dans les architectures web plus anciennes, les développeurs collaient parfois les mots de passe et signatures API PayPal directement dans les définitions de champs de formulaire ou les paramètres d'un modèle. Dans Passinstance, cette pratique est strictement rejetée :
Important : dans
forms.service.ts(ligne 1269), le backend Passinstance appliquerejectLegacySecretWrites. Toute tentative d'enregistrement de secrets de paiement bruts (payPalApiUsername,payPalApiPasswordoupayPalApiSignature) dans les définitions publiques de formulaires ou les métadonnées de modèles renvoie immédiatement une erreurBadRequestException.
Les identifiants de paiement doivent être configurés une seule fois au niveau de l'espace de travail avec les identifiants REST OAuth (Client ID et Client Secret), où ils sont chiffrés dans le coffre-fort du locataire et isolés des formulaires publics d'inscription.
Guide étape par étape : obtenir des identifiants REST PayPal
Suivez ces étapes pour générer vos identifiants API REST PayPal depuis le portail officiel PayPal Developer :
Étape 1 : vous connecter au portail PayPal Developer
-
1
Ouvrez developer.paypal.com dans votre navigateur.
-
2
Cliquez sur Log In to Dashboard en haut à droite et authentifiez-vous avec votre compte PayPal Business.
Étape 2 : ouvrir « Apps & Credentials »
-
1
Dans le menu de navigation gauche, cliquez sur Apps & Credentials.
-
2
Sélectionnez votre environnement :
- Sandbox : utilisez les identifiants Sandbox pour tester votre parcours de passe et concevoir vos modèles. - Live : utilisez les identifiants Live dès que vous êtes prêt à encaisser de vrais paiements clients.
Étape 3 : créer une nouvelle application REST API
-
1
Cliquez sur le bouton Create App.
-
2
Dans le champ App Name, saisissez un nom explicite (par ex.
Passinstance Wallet Payments). -
3
Définissez App Type sur Merchant.
-
4
Si vous possédez plusieurs comptes professionnels Sandbox, sélectionnez le compte de test souhaité.
-
5
Cliquez sur Create App.
Étape 4 : copier le Client ID & le Client Secret
PayPal ouvre la page de détails de votre application :
-
Copiez la chaîne Client ID.
-
Sous Secret, cliquez sur Show et copiez le Client Secret. Conservez ce secret strictement confidentiel.
Configurer PayPal dans votre espace de travail Passinstance
Une fois vos identifiants REST en main, connectez PayPal à votre espace de travail :
Via le tableau de bord :
-
1
Accédez à Paramètres -> Intégrations -> Paiements (
/settings/integrations/payments). -
2
Localisez PayPal et cliquez sur Connecter (Connect).
-
3
Choisissez votre environnement (Sandbox ou Live).
-
4
Collez votre Client ID et votre Client Secret.
-
5
Sélectionnez votre devise par défaut (par ex.
EUR,USD,GBP). -
6
Cliquez sur Enregistrer & tester la connexion (Save & Test Connection). Passinstance réalise un test d'authentification OAuth automatisé pour confirmer la validité des identifiants avant d'activer la passerelle.
Via l'API REST (POST /payments/admin/:customerId/integrations) :
POST /api/v1/payments/admin/{customerId}/integrations HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json
{
"provider": "PAYPAL",
"clientId": "AWr_7B8c9D0e1F2G3H4I5J6K7L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2",
"clientSecret": "EPa_1B2c3D4e5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6",
"mode": "live",
"currency": "EUR"
}
Réponse (201 Created) :
{
"success": true,
"data": {
"provider": "PAYPAL",
"mode": "live",
"currency": "EUR",
"status": "ACTIVE",
"webhookUrl": "https://api.passinstance.com/api/v1/payments/webhooks/paypal"
},
"description": "PayPal integration configured successfully",
"statusCode": 201
}
Configurer le webhook PayPal pour l'émission instantanée des passes
Pour émettre les passes immédiatement après la capture du paiement, enregistrez l'endpoint webhook de Passinstance dans votre portail PayPal Developer :
-
1
Sur la page de votre application PayPal sous Apps & Credentials, faites défiler jusqu'à Webhooks.
-
2
Cliquez sur Add Webhook.
-
3
Dans le champ Webhook URL, saisissez l'endpoint webhook de votre espace de travail :
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
4
Sous Event Types, cochez les événements suivants :
- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)
-
5
Cliquez sur Save. Copiez le Webhook ID généré et collez-le dans Passinstance au sein de vos paramètres d'intégration PayPal.
Lorsqu'un client autorise un paiement dans PassFlow, PayPal notifie Passinstance via ce webhook. Passinstance vérifie l'en-tête cryptographique PAYPAL-TRANSMISSION-SIG, émet la fiche du passe et le met à disposition pour le portefeuille du client.
Dépannage des erreurs PayPal courantes
| Code d'erreur / Message | Cause racine | Solution |
|---|---|---|
INVALID_CLIENT | Le Client ID ou le Secret est incorrect, ou des identifiants Sandbox ont été saisis en mode Live. | Vérifiez que les identifiants ont été copiés exactement et que le mode d'environnement (Sandbox vs Live) concorde dans les deux systèmes. |
AUTHENTICATION_FAILURE | Le Client Secret a été réinitialisé dans PayPal ou contient des espaces en début/fin de chaîne. | Générez un nouveau Client Secret dans le tableau de bord développeur PayPal puis enregistrez-le de nouveau dans Passinstance. |
CURRENCY_NOT_SUPPORTED | La devise définie dans PassFlow (par ex. JPY ou BRL) n'est pas activée sur votre compte marchand PayPal. | Connectez-vous à votre compte PayPal Business -> Paramètres du compte -> Devises et activez la devise cible. |
| Passe non émis après paiement | Le webhook PayPal est manquant ou bloqué par un pare-feu. | Vérifiez que l'URL webhook est enregistrée dans PayPal avec l'événement PAYMENT.CAPTURE.COMPLETED activé. Consultez Activité & journaux dans Passinstance pour contrôler les horodatages de réception des webhooks. |
Documentation connexe
-
Vendre des passes — Guide complet pour configurer des passes et billets payants dans PassFlow.
-
Vendre des abonnements — Gérer des adhésions récurrentes avec PayPal Subscriptions.
-
Moyens de paiement — Gérer les moyens de paiement de facturation de votre espace de travail.
