Encaisser avec Payplug depuis votre logiciel métier

Ce que l'API Payplug sait faire, fonction par fonction

L'API Payplug couvre l'encaissement, le remboursement et plusieurs usages plus avancés, que son journal des modifications permet de dater. Le tableau reprend les fonctions utiles à un logiciel métier, d'après la référence de l'API et ce journal consultés en octobre 2026.

Clés, version d'API et mode test

Chaque appel à l'API Payplug porte la clé secrète du compte dans l'en-tête Authorization, au format Bearer, et passe obligatoirement en HTTPS. Le mode test et la production partagent la même adresse, https://api.payplug.com : c'est la clé qui choisit le mode, sk_test_ ou sk_live_. Les clés se trouvent dans le portail Payplug, et les cartes de test publiées par Payplug ne fonctionnent qu'en mode test (elles ne couvrent pas Bancontact).

L'en-tête PayPlug-Version fixe la version de l'API, 2019-08-06 dans la référence consultée ; sans lui, l'appel retombe sur une ancienne version. Les montants s'expriment en centimes, en nombres entiers positifs, et les listes se paginent par 100 éléments au plus. La documentation consultée en octobre 2026 ne publie pas de limite de débit : avant une reprise de données ou un traitement de masse, mieux vaut poser la question au support Payplug.

Payplug fournit des bibliothèques officielles en PHP et en Python. Un logiciel écrit en Node.js, en Java ou en C# appelle l'API REST directement, ce qui ne pose pas de difficulté, mais il faut alors reproduire soi-même la relecture des notifications que ces bibliothèques automatisent.

Pourquoi une notification Payplug ne suffit pas à valider un paiement

Payplug prévient votre serveur par une requête POST vers l'adresse notification_url fournie à la création du paiement. Le message contient l'identifiant de l'objet, son type et l'indicateur is_live ; la documentation ne décrit pas de signature et présente la relecture de l'objet par son identifiant, en HTTPS, comme le moyen d'en vérifier l'authenticité. Sans cette relecture, un tiers qui connaîtrait l'adresse pourrait faire passer une commande pour payée.

Deux conséquences pour le logiciel. L'adresse de notification doit être joignable depuis internet : un serveur interne derrière un pare-feu ne reçoit rien. Et un client qui abandonne ne déclenche aucun message : une tâche planifiée relit les paiements restés en attente pour libérer le stock réservé ou relancer. Payplug envoie aussi au titulaire du compte un courriel « Notification Error » quand une notification échoue ; il doit arriver chez quelqu'un qui sait quoi en faire.

Exemples concrets, de la facture au paiement encaissé

• La facture payable par SMS. Un technicien clôture son intervention ; le logiciel d'interventions crée une demande de paiement Payplug avec sent_by à SMS (le numéro de téléphone est alors obligatoire). Le client paie sur son téléphone, la notification arrive, le logiciel relit le paiement et solde la facture. Voir notre page pour digitaliser les bons d'intervention.
• Le lien glissé dans un courriel. Avec sent_by à OTHER, Payplug génère un lien sans expiration que le logiciel insère lui-même dans son propre courriel de relance ; avec la valeur NULL, le lien expire 15 minutes après la première ouverture.
• La précommande. Un fabricant autorise le paiement à la commande et ne le capture qu'à l'expédition, grâce au paiement différé.
• La formation en plusieurs fois. Un organisme crée un échéancier Payplug à l'inscription ; si le stagiaire se désiste, le logiciel annule l'échéancier par l'API. Le métier est décrit sur notre page logiciel pour organisme de formation.
• Le geste commercial. Le service client accorde un remboursement partiel depuis le back-office ; l'attribut amount_refunded du paiement indique le total déjà rendu.
• La clôture du mois. Le logiciel demande un rapport comptable par l'API et le range avec les pièces destinées à l'expert-comptable.

Points de vigilance propres à Payplug

• Les métadonnées : une mise à jour remplace toutes les clés. Le logiciel renvoie donc les métadonnées existantes à chaque modification, sous peine de perdre la référence de commande qui relie le paiement à son dossier.
• Les remboursements : un remboursement doit dépasser 10 centimes, et un paiement intégralement remboursé ne peut plus l'être.
• Les erreurs : les codes 5xx signalent un incident temporaire côté Payplug, que la documentation conseille de réessayer quelques minutes plus tard. Les codes d'échec (card_declined, insufficient_funds, 3ds_declined, fraud_suspected) se traduisent en messages compréhensibles pour le client.
• Les coupures réseau : le logiciel enregistre l'identifiant du paiement dès la réponse et, après une coupure, consulte la liste des paiements avant d'en recréer un.
• Les données personnelles : les blocs billing et shipping contiennent nom, adresse et téléphone. N'envoyez que ce qui est utile et ne placez jamais de donnée sensible dans les métadonnées ; notre guide sécuriser une application métier traite aussi de la garde des clés.

Module e-commerce Payplug ou développement sur mesure ?

Pour une boutique en ligne classique, Payplug oriente les équipes sans développeur vers ses modules pour plateformes e-commerce : c'est la voie la plus simple, et un développement n'apporterait rien. Le sur mesure se justifie quand le paiement part d'un logiciel métier (interventions, formation, location, prise de commande) et doit mettre à jour ses propres dossiers, ce qu'aucun module de boutique ne fait. Pour des prélèvements récurrents sur compte bancaire, le besoin relève plutôt du prélèvement SEPA, décrit sur notre page intégration GoCardless.

Ce que YMHB Web livre avec une intégration Payplug

Pour YMHB Web, une intégration Payplug se juge à sa capacité à dire, pour chaque dossier, si l'argent est réellement encaissé. Le cadrage fixe les moments où le logiciel crée un paiement, les statuts métier qui en dépendent et le sort des paiements abandonnés ; le chiffrage suit. Le développement et la recette se font avec les clés de test de votre compte, puis la mise en service bascule sur la clé de production.

• un point de réception des notifications qui relit systématiquement l'objet avant d'agir ;
• une tâche planifiée qui reprend les paiements restés sans réponse ;
• un journal des appels et des notifications, et un écran des paiements en anomalie ;
• le code, déposé chez vous et documenté, et des clés qui restent dans votre compte Payplug.

Le cadre général de ces connexions est présenté sur notre page connecter ses logiciels par API.