--- title: PayPal description: Connectez PayPal à NexCMP pour le rechargement de portefeuille — identifiants d'application REST, webhook, tests sandbox et comptes PayPal enregistrés. url: https://nexcmp.com/fr/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # PayPal > **Dans l'administration :** Finance › Payment channels › PayPal (`/payments/paypal`). L'interrupteur marche/arrêt et les frais se trouvent dans Finance › Payment channels › Fees & limits (`/payments/fees`). ## Description {#what-it-does} Permet aux clients de recharger leur portefeuille en USD avec leur solde PayPal, leur compte bancaire ou une carte enregistrée sur PayPal. Les clients peuvent également autoriser NexCMP à mémoriser leur compte PayPal pour le [rechargement automatique](https://nexcmp.com/fr/docs/billing/auto-top-up/). À utiliser en parallèle de [Stripe](https://nexcmp.com/fr/docs/billing/stripe/) pour les clients qui préfèrent PayPal. ## Prérequis {#requirements} | Élément | Prérequis | |---|---| | Compte PayPal | Un compte PayPal **Business** capable de recevoir des USD. | | Application REST | Une application REST dans le tableau de bord des développeurs PayPal (**Apps & Credentials**) fournissant un **Client ID** et un **Client secret**. Utilisez l'onglet **Sandbox** pour les tests et **Live** pour la production. | | Réseau | HTTPS accessible depuis Internet (PayPal appelle le webhook) et accès sortant vers `api-m.paypal.com` (production) ou `api-m.sandbox.paypal.com` (bac à sable), port 443. | | Permissions | L'application REST nécessite les fonctionnalités de remboursement et de webhooks. La boîte de dialogue **Check** indique si les deux portées sont présentes. | | Dépendances | Aucune. | ## Préparer l'infrastructure {#prepare-the-infrastructure} 1. Connectez-vous à [developer.paypal.com](https://developer.paypal.com) avec votre compte Business et ouvrez **Apps & Credentials**. 2. Choisissez **Sandbox** (tests) ou **Live**, puis cliquez sur **Create App**. Donnez-lui un nom, par exemple "NexCMP". 3. Copiez le **Client ID** et le **Secret** de l'application. 4. Pour les tests, utilisez **Testing Tools › Sandbox Accounts** pour trouver ou créer un compte sandbox *Personnel* (acheteur). 5. Vous n'avez pas besoin de créer le webhook vous-même ; NexCMP le crée avec le bouton **Create webhook**. ## Connecter dans NexCMP {#connect-in-nexcmp} 1. Ouvrez **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. Dans **API keys**, choisissez **Mode** : `live` (argent réel, `api-m.paypal.com`) ou `sandbox` (`api-m.sandbox.paypal.com`). 3. Collez le **Client ID** (au moins 20 caractères) et le **Client secret**. 4. Cliquez sur **Check**. Cela teste les identifiants saisis (l'enregistrement n'est pas requis) et indique la connexion, l'ID d'application, le mode, la présence des portées de remboursement et de webhooks, ainsi que la durée de vie du jeton. 5. Cliquez sur **Save**. 6. Dans la carte **Webhook**, confirmez que l'URL est `https:///v1/billing/paypal/webhook` (elle doit être `https`), puis cliquez sur **Create webhook** et confirmez. NexCMP demande à PayPal de créer ou de mettre à jour le webhook avec 11 événements et enregistre le **Webhook ID** renvoyé. Le bouton utilise les clés **enregistrées** — enregistrez d'abord si vous venez de les modifier. 7. Cliquez à nouveau sur **Check** : la ligne **Webhook** doit indiquer "exists, 11 events". 8. Ouvrez **Fees & limits**, activez **PayPal**, définissez **PayPal fee %** (par défaut 4.4) et **PayPal fixed fee (cents)** (par défaut 30) selon votre tarif, puis cliquez sur **Save channels & fees**. ![Page PayPal avec le mode sandbox et des exemples d'identifiants saisis](https://nexcmp.com/fr/docs/images/billing/paypal-01-keys.webp) ### Événements de webhook {#webhook-events} NexCMP enregistre ces 11 événements : `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Chaque webhook est vérifié en appelant l'API de vérification de signature de PayPal, stocké une seule fois et traité de manière idempotente. NexCMP ne fait jamais confiance au montant contenu dans le corps du webhook : avant de créditer une capture, il récupère la capture auprès de PayPal. ## Vérification {#verify} 1. Laissez **Mode** sur `sandbox`. Dans le portail, ouvrez **Billing › Deposit**, choisissez **PayPal**, cliquez sur **Continue on PayPal** (ou sur le bouton PayPal) et connectez-vous avec le compte acheteur sandbox. 2. Approuvez le paiement. Vous retournez sur le portail, le solde augmente et le paiement apparaît sous **Finance › Billing › Top-ups** avec le statut *Completed*. 3. Ouvrez **Payment channels › Gateway events › PayPal & USDT** : l'événement `PAYMENT.CAPTURE.COMPLETED` est répertorié. 4. Lorsque tout fonctionne, basculez **Mode** sur `live`, saisissez les identifiants de production, **Save**, puis cliquez à nouveau sur **Create webhook** (les webhooks sandbox et de production sont distincts). ## Limites et notes {#limits-notes} - **Comment un paiement se finalise.** La commande est créée en USD ; après son approbation par le client, le **serveur** effectue la capture (ID de requête idempotent) et crédite le portefeuille exactement une fois. Le webhook et une tâche de réconciliation exécutée toutes les 10 minutes constituent des filets de sécurité si le client ferme son navigateur. - **Commandes en attente et abandonnées.** Une commande peut rester ouverte pendant 12 heures. Un client peut avoir au maximum 5 commandes en attente (le serveur répond `too_many_pending`, HTTP 429). Une commande toujours non capturée après 24 heures est marquée comme échouée. - **Aucun webhook configuré.** Le panneau répond par HTTP 503 à chaque webhook PayPal tant qu'un Webhook ID n'est pas enregistré. Les captures effectuées via le portail et la réconciliation toutes les 10 minutes créditent toujours le portefeuille, mais rien de ce que PayPal signale par webhook (litiges, annulations, captures tardives) n'est appliqué — cliquez sur **Create webhook**. - **Compte PayPal enregistré.** Lorsque le client choisit d'enregistrer PayPal (ou effectue le premier dépôt, ce qui active le [top-up automatique](https://nexcmp.com/fr/docs/billing/auto-top-up/)), PayPal stocke le jeton de paiement dans son coffre-fort. NexCMP conserve uniquement un identifiant et l'e-mail PayPal. Voir [Saved payment methods](https://nexcmp.com/fr/docs/billing/saved-payment-methods/). - **Remboursements et litiges.** Ils sont gérés comme pour Stripe : les demandes de remboursement sont approuvées sous **Finance › Payouts › Card refunds** ; un litige bloque le compte du client et suspend ses services prépayés jusqu'à sa résolution. - **Frais.** Les frais de PayPal ne sont pas relus automatiquement ; le pourcentage et les frais fixes configurés déterminent ce que le client voit et ce qui est crédité. Le tarif réel dépend de votre pays (le formulaire indique 4.4 % pour le Vietnam et 3.49 % pour les États-Unis). ## Dépannage {#troubleshooting} | Symptôme | Cause | Solution | |---|---|---| | "Client ID trop court" | Moins de 20 caractères collés | Copiez l'ID client complet. | | "L'URL du webhook doit être en https" | URL saisie avec `http://` | Utilisez votre domaine public `https://`. | | La vérification signale une erreur de connexion | Mode incorrect (clés live en sandbox ou l'inverse), secret erroné, pas d'accès sortant | Faites correspondre **Mode** au type de clé ; testez `curl -I https://api-m.paypal.com` depuis le serveur. | | La portée remboursement / webhooks indique "no" | L'application REST ne dispose pas des fonctionnalités | Activez les fonctionnalités sur l'application dans le tableau de bord développeur PayPal. | | Banniere "PayPal key set, NO webhook" | ID de webhook manquant | Cliquez sur **Create webhook**. | | "Webhook not found" lors de la vérification | Le webhook a été supprimé chez PayPal ou appartient à une autre application | Cliquez à nouveau sur **Create webhook**. | | Il est indiqué au client que PayPal a refusé le paiement | PayPal a rejeté cette source de financement | Demandez au client de choisir une autre source de paiement. | | Le client voit "Too many pending requests" | 5 commandes ouvertes | Attendez qu'elles expirent ou finalisez-les. | | Bouton PayPal manquant | PayPal désactivé dans **Fees & limits** ou non configuré | Activez-le et enregistrez les identifiants. |