Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Paiements

PayPal

Connecter un compte PayPal pour encaisser des paiements en ligne.

PayPal

L'intégration PayPal permet à vos clients de payer avec leur compte PayPal. Elle utilise l'API REST de PayPal (Orders v2 et Subscriptions v2).

Ce que l'intégration permet

  • Payer une Demande de paiement liée à une commande client ou une facture de vente, par un lien de paiement. Le client approuve le paiement sur PayPal. À son retour sur votre site, Dokos encaisse le paiement.
  • Payer une commande sur le site e-commerce, si le mode de paiement PayPal y est autorisé.
  • Comptabiliser chaque jour les frais PayPal des paiements de la veille.

Prérequis

  • Un compte PayPal Business.
  • Une application REST créée sur developer.paypal.com, avec son identifiant client et son secret client.
  • Facultatif : les identifiants de l'API classique de PayPal (nom d'utilisateur, mot de passe et signature). Ils ne sont utiles que pour les liens de paiement et les profils récurrents créés avec l'ancien flux v1.

Configurer PayPal

Le site a un seul document Paramètres PayPal, donc un seul compte PayPal.

  1. Dans l'espace Passerelles de paiement, ouvrez Paramètres PayPal.
  2. Renseignez les champs suivants :
    ChampContenu
    Identifiant clientSection API REST (Orders v2). Identifiant client de l'application REST.
    Secret clientSecret client de l'application REST.
    ID du plan d'abonnementFacultatif. Plan PayPal utilisé quand une demande de paiement de 0 € sert à enregistrer le moyen de paiement d'un abonnement.
    URL du webhookLecture seule. Adresse à déclarer dans PayPal (voir ci-dessous). Elle s'affiche après le premier enregistrement.
    ID du webhookIdentifiant du webhook déclaré dans l'application REST. Dokos s'en sert pour faire vérifier par PayPal la signature de chaque notification. Sans cet identifiant, Dokos rejette toutes les notifications.
    Utiliser la sandboxSection Paramètres. Cochez si les identifiants viennent d'un compte de test (sandbox) PayPal.
    Rediriger versFacultatif. Page où le client arrive s'il annule le paiement.
    Nom d'Utilisateur API, Mot de passe API, SignatureSection repliable Ancienne API (NVP / Express Checkout). Facultatif : nécessaire uniquement pour les liens de paiement et les profils récurrents créés avec le flux v1. Ce flux est obsolète.

    Pour obtenir l'ID du webhook, déclarez un webhook dans votre application REST PayPal, avec l'adresse affichée dans le champ URL du webhook (de la forme https://votre-site.fr/api/method/payments.webhooks.handle?gateway=PayPal). Abonnez-le aux événements PAYMENT.CAPTURE.*, CHECKOUT.ORDER.* et BILLING.SUBSCRIPTION.*. PayPal affiche alors l'identifiant du webhook : copiez-le dans ID du webhook, puis enregistrez de nouveau.
  3. Enregistrez. Dokos vérifie les identifiants à l'enregistrement :
    • Identifiant client et Secret client renseignés : Dokos demande un jeton d'accès à PayPal. Si PayPal refuse les identifiants, Dokos affiche « ID client ou secret client de l'API REST PayPal invalide. ». Dokos affiche aussi ce message quand PayPal répond par une erreur de son côté, par exemple une indisponibilité temporaire. Si vos identifiants sont corrects, réessayez plus tard. Si PayPal est injoignable (pas de réponse, délai dépassé), Dokos affiche « PayPal n'a pas pu être contacté pour vérifier les identifiants de l'API REST » suivi du détail de l'erreur.
    • Un seul des deux champs renseigné : Dokos affiche « Saisissez à la fois l'ID client et le secret client de l'API REST PayPal. ».
    • Aucun identifiant renseigné : Dokos refuse l'enregistrement avec « Saisissez l'ID client et le secret client de l'API REST PayPal. ».
    • Un champ de la section Ancienne API (NVP / Express Checkout) renseigné : Dokos vérifie aussi ces identifiants auprès de PayPal. S'ils sont faux, il affiche « Identifiants de la passerelle de paiement invalides ». Sans champ NVP rempli, cette vérification n'a pas lieu.

    Dokos crée la passerelle de paiement PayPal.
  4. Dans la section Configuration du paiement, ajoutez un compte de paiement et un mode de paiement pour chaque société. Renseignez le Clearing Account (compte d'attente) du mode de paiement. Voir Configurer une passerelle.

Exemple fictif : vous créez une application REST sandbox. Vous saisissez son identifiant client et son secret client, vous cochez Utiliser la sandbox et vous laissez la section Ancienne API (NVP / Express Checkout) vide. À l'enregistrement, Dokos contrôle les deux valeurs auprès de PayPal et affiche l'URL du webhook. Vous la déclarez dans l'application REST, vous copiez l'identifiant du webhook dans ID du webhook, puis vous enregistrez de nouveau.

Le parcours de paiement

  1. Le client ouvre le lien de la demande de paiement. Dokos crée une commande chez PayPal et redirige le client vers PayPal.
  2. Le client approuve le paiement, puis revient sur votre site.
  3. Dokos encaisse la commande chez PayPal. Il ne l'encaisse jamais deux fois, même si le client recharge la page.
  4. Si le paiement aboutit, la demande de paiement passe à Payé et Dokos crée l'écriture de paiement.

Chaque tentative de paiement est suivie dans le Journal des sessions de paiement. Si le client ne revient pas sur votre site, Dokos interroge PayPal à intervalles réguliers. Si le résultat reste inconnu après 72 heures, Dokos crée un Problème de rapprochement de paiement.

Comptabilisation

PayPal est une passerelle v2. Dokos passe chaque paiement au montant brut sur le Clearing Account du mode de paiement.

PayPal ne fait pas de virement par paiement : l'argent reste sur le solde PayPal. Chaque jour, Dokos lit les transactions PayPal réglées la veille. Il crée un Versement pour cette journée, avec le montant brut, les frais et le net de chaque transaction. À sa validation, Dokos passe une écriture de journal qui comptabilise les frais et solde le compte d'attente. Les remboursements et les retraits ne font pas partie de ce versement.

Voir Passerelles de paiement.

Exemple

Exemple fictif : le 4 mars, trois clients paient chacun une facture de 50 € avec PayPal. Dokos passe 3 × 50 € sur le compte d'attente. Le 5 mars, Dokos lit les transactions du 4 mars. Il crée un Versement de 150 € brut, avec les frais prélevés par PayPal. L'écriture de journal passe les frais en charge et solde le compte d'attente.

Limites

  • Devises acceptées : AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RUB, SEK, SGD, THB, TRY, TWD et USD.
  • Le site gère un seul compte PayPal.

Tester

  1. Créez une application REST de type sandbox sur developer.paypal.com.
  2. Saisissez ses identifiants dans les Paramètres PayPal et cochez Utiliser la sandbox.
  3. Créez une demande de paiement avec la passerelle PayPal. Ouvrez le lien de paiement dans une fenêtre de navigation privée et payez avec un compte acheteur de test.