Introduction
Créez des sessions de paiement et suivez les transactions via les passerelles configurées dans votre projet.
Plus d'informations sur les paiements dans le panneau d'administration OneEntry : https://doc.oneentry.cloud/docs/category/payments
🎯 Que fait ce module ?
Le module Payments vous permet de gérer le traitement des paiements et les transactions pour votre boutique e-commerce. Travailler avec les paiements et les transactions est une partie importante de tout projet e-commerce. Il s'intègre à des passerelles de paiement comme Stripe pour gérer les sessions de paiement, le suivi des transactions et la gestion des statuts de paiement.
Considérez-le comme votre système de gestion des paiements - vous configurez les comptes de paiement dans le panneau d'administration OneEntry (Payments > Accounts), créez plusieurs comptes pour différents types de paiements tels que la connexion à un système de paiement ou l'ajout de paiements en espèces, et ce module gère la création de sessions de paiement, le suivi des statuts et la gestion des transactions.
📖 Explication Simple
Chaque application e-commerce a besoin d'un traitement des paiements sécurisé :
- 💳 Accepter les paiements - Cartes de crédit, cartes de débit, portefeuilles numériques
- 🔒 Traitement sécurisé - Gestion des paiements conforme à la norme PCI
- 🔄 Statut des paiements - Suivez les paiements en attente, complétés, échoués, remboursés
- 💰 Remboursements - Traitez les remboursements complets ou partiels
- 📊 Historique des paiements - Consultez toutes les transactions
- 🔗 Intégration de passerelles - Stripe, PayPal, passerelles personnalisées
Le problème avec la gestion manuelle des paiements :
Problèmes :
- 🔒 Risque de sécurité - Stockage de données sensibles de carte
- 📋 Conformité PCI - Certification coûteuse requise
- 💸 Pas de suivi des remboursements - Gestion manuelle des remboursements
- 🔄 Pas d'historique des paiements - Difficile de suivre les transactions
La solution Payments :
Avantages :
- 🔒 Conforme PCI - Paiements sécurisés par tokenisation
- 📊 Suivi des paiements - Historique complet des transactions
- 🔄 Remboursements automatisés - Traitement facile des remboursements
- 💸 Multiples passerelles - Stripe, PayPal, personnalisées
✨ Concepts Clés
Qu'est-ce qu'un Paiement ?
Un Paiement est un enregistrement de transaction financière contenant :
- Méthode de paiement - Carte, PayPal, virement bancaire
- Montant - Montant de la transaction et devise
- Référence de commande - ID de commande associée
- Statut de paiement - En attente, complété, échoué, remboursé
- Détails de la passerelle - ID de transaction Stripe, référence PayPal
- Informations client - Détails de facturation
- Horodatages - Dates de création, de traitement, de complétion
Types de Comptes Disponibles
| Type | Quand l'utiliser | Configuration requise |
|---|---|---|
| Stripe | Connectez le système de paiement Stripe à votre projet | Compte Stripe, URLs |
| Personnalisé | Systèmes de paiement alternatifs ou paiements en espèces | Configuration personnalisée |
Cycle de Vie du Paiement
1. Create payment account in admin panel
(Configure Stripe or custom account)
↓
2. Customer places order
(Order created in Orders module)
↓
3. Create payment session
(Payments.createSession(orderId, type))
↓
4. Customer redirected to payment URL
(Stripe checkout or custom payment page)
↓
5. Customer completes payment
(Payment processed by gateway)
↓
6. Payment status updated
(waiting → pending → paid/canceled/expired)
↓
7. Notification received
↓
8. Order status synchronized
(Payment status linked to order status)
Statuts de Paiement
Le système comprend quatre statuts de paiement prédéfinis qui indiquent l'état de la transaction en cours de traitement :
| Statut | Signification | Quand cela se produit |
|---|---|---|
| En attente | État initial de la transaction | Session de paiement juste créée |
| Payé | Transaction complétée avec succès | Paiement confirmé par la passerelle |
| Annulé | Transaction annulée | Le client a annulé le paiement |
| Expiré | Période de validité de la transaction terminée | Délai de session dépassé |
Important : Dans les paramètres de paiement, vous ne pouvez pas créer ou modifier des statuts. Cependant, vous pouvez lier ces statuts de paiement prédéfinis aux statuts de stockage des commandes pour permettre une synchronisation automatique entre les systèmes de paiement et de commande.
Méthodes de Paiement
| Méthode | Description | Support de passerelle |
|---|---|---|
| carte_de_crédit | Visa, Mastercard, Amex | Stripe, PayPal |
| carte_de_débit | Cartes de débit | Stripe, PayPal |
| paypal | Compte PayPal | PayPal |
| virement_bancaire | Virement, ACH | Personnalisé |
| apple_pay | Portefeuille Apple Pay | Stripe |
| google_pay | Portefeuille Google Pay | Stripe |
| paiement_à_la_livraison | Paiement à la livraison | N/A |
Pourquoi Utiliser le Module Payments ?
| Avantage | Description |
|---|---|
| Conformité PCI | Traitement sécurisé des paiements par tokenisation |
| Intégration de passerelle | Intégration Stripe, PayPal intégrée |
| Suivi des paiements | Historique complet des transactions |
| Gestion des remboursements | Remboursements complets/partiels faciles |
| Protection contre la fraude | Détection de fraude intégrée |
| 3D Secure | Support de l'authentification SCA |
| Multi-devises | Support pour plusieurs devises |
📋 Ce que Vous Devez Savoir
Les Comptes de Paiement sont Créés dans le Panneau d'Administration
Vous ne pouvez pas créer de comptes de paiement via le SDK - ils sont créés dans le panneau d'administration OneEntry :
OneEntry Admin Panel → Payments → Accounts → Create Account → Fill Form → Click "Add"
Processus de création :
- Remplissez le formulaire avec trois champs requis :
- Nom - Identifiant de chaîne non unique
- Type - Sélectionné dans le menu déroulant : "Stripe" ou "Personnalisé"
- Token - Identifiant de chaîne unique
- Cliquez sur "Ajouter" pour créer le compte
Gestion des comptes :
- Édition - Sélectionnez le compte, cliquez sur l'icône d'édition, modifiez le nom/type/token/paramètres Stripe
- Masquage - Cliquez sur l'icône de l'œil pour masquer les comptes des sélections de configuration de stockage des commandes
- Suppression - Sélectionnez le compte, cliquez sur l'icône de suppression, confirmez la suppression
Le SDK est destiné à récupérer les comptes de paiement et créer des sessions de paiement, pas à gérer les comptes.
Types de Comptes de Paiement
Deux types de comptes de paiement sont disponibles :
| Type | Description |
|---|---|
| Stripe | Choisissez ce type pour connecter le système de paiement Stripe |
| Personnalisé | Pour des systèmes de paiement alternatifs ou des paiements en espèces |
Configuration spécifique à Stripe :
- URL de succès - URL de redirection après un paiement réussi
- URL d'annulation - URL de redirection si le paiement est annulé
- Durée de session - Délai de session en minutes
Synchronisation des Statuts de Paiement
Les statuts de paiement peuvent être liés aux statuts de stockage des commandes :
OneEntry Admin Panel → Payments → Statuses → Select Order Storage → Map Statuses → Save
Flux de travail de mappage des statuts :
- Accédez à la sous-section Statuts dans Payments
- Sélectionnez le système de stockage des commandes souhaité
- Mappez chaque statut de paiement prédéfini à la valeur de statut de stockage des commandes correspondante
- Vérifiez que tous les mappages sont exacts
- Cliquez sur Enregistrer pour appliquer les modifications
Cela permet des mises à jour automatiques des statuts dans les enregistrements de commandes lorsque les statuts de paiement changent.
Ne Jamais Stocker de Données de Carte Brutes
CRITIQUE : Ne jamais stocker les numéros de carte de crédit, CVV ou dates d'expiration complètes.
Pourquoi ?
- La conformité PCI DSS exige un traitement sécurisé
- Le stockage des données de carte vous expose à des responsabilités
- OneEntry ne stocke jamais les détails de carte bruts
💡 Notes Importantes
Les Comptes de Paiement sont Créés dans le Panneau d'Administration
Rappelez-vous : Le SDK est destiné à récupérer les comptes de paiement et créer des sessions, pas à créer des comptes.
Pour créer/éditer des comptes de paiement : Utilisez le Panneau d'Administration OneEntry.
Gestion des Comptes de Paiement
Création de comptes dans le panneau d'administration :
- Accédez à Payments > Accounts
- Remplissez le formulaire avec le Nom, le Type et le Token
- Pour les comptes Stripe, configurez l'URL de succès, l'URL d'annulation et la durée de session
- Cliquez sur "Ajouter" pour créer
Gestion des comptes :
- Éditer - Modifiez le nom, le type, le token ou les paramètres spécifiques à Stripe
- Masquer - Cliquez sur l'icône de l'œil pour masquer de la configuration de stockage des commandes (ne supprime pas)
- Supprimer - Supprimez complètement les comptes inutilisés
Important : Seuls les comptes inutilisés peuvent être supprimés.
Configuration des Statuts de Paiement
Important : Vous ne pouvez pas créer ou modifier des statuts de paiement dans le panneau d'administration. Le système a quatre statuts prédéfinis : En attente, Payé, Annulé, Expiré.
Flux de travail de synchronisation des statuts :
- Accédez à Payments > Statuses
- Sélectionnez le système de stockage des commandes
- Mappez les statuts de paiement prédéfinis aux statuts de stockage des commandes
- Cliquez sur Enregistrer pour appliquer les modifications
Cela permet des mises à jour automatiques des statuts de commande lorsque les statuts de paiement changent.
Types de Session
Deux types de session sont disponibles :
| Type | Description |
|---|---|
| session | Crée une page de paiement Stripe Checkout avec un lien de paiement |
| intent | Crée une intention de paiement pour un traitement direct des paiements |
Sécurité d'abord
🔒 Règles de sécurité critiques :
- Ne jamais stocker de données de carte brutes - Utilisez la tokenisation
- Utilisez uniquement HTTPS - Toutes les pages de paiement doivent être SSL
- Validez sur le serveur - Ne faites jamais confiance aux données côté client
- Enregistrez les transactions - Conservez une trace d'audit
- Traitez les PII avec soin - Protégez les données des clients
Conformité PCI
✅ OneEntry gère la conformité PCI pour vous :
- Traitement des paiements par tokenisation
- Intégration sécurisée de la passerelle
- Pas de stockage de données de carte brutes
- Transmission cryptée
Votre responsabilité :
- Utilisez HTTPS sur les pages de paiement
- Ne pas enregistrer de données sensibles
- Suivez les meilleures pratiques de sécurité
Polling des Statuts de Paiement
Pour les paiements asynchrones, interrogez les mises à jour de statut :
Limitations des Remboursements
Règles importantes sur les remboursements :
- Ne peut rembourser que les paiements complétés
- Les remboursements partiels ne doivent pas dépasser le montant d'origine
- Certaines passerelles ont des limites de temps (par exemple, 180 jours)
- Les remboursements sont asynchrones (peuvent prendre des jours)
📊 Tableau de Référence Rapide
| Méthode | Description | Cas d'utilisation |
|---|---|---|
| getAccounts() | Obtenez tous les comptes de paiement | Liste des méthodes de paiement disponibles |
| getAccountById() | Obtenez le compte de paiement par ID | Récupérer les détails d'un compte spécifique |
| createSession() 🔐 | Créez une session de paiement | Générer un lien de paiement pour la commande |
| getSessions() 🔐 | Obtenez toutes les sessions de paiement (paginé) | Voir l'historique des sessions de paiement |
| getSessionById() 🔐 | Obtenez la session de paiement par ID | Vérifiez le statut d'une session spécifique |
| getSessionByOrderId() 🔐 | Obtenez la session de paiement par ID de commande | Trouvez le paiement pour une commande spécifique |
🔐 = Nécessite une autorisation
❓ Questions Fréquemment Posées (FAQ)
Comment configurer les paiements Stripe ?
Créez un compte de paiement dans le panneau d'administration avec le type "Stripe", puis configurez l'URL de succès, l'URL d'annulation et la durée de session. Utilisez createSession() pour générer des liens de paiement qui redirigent les clients vers Stripe Checkout.
Quelle est la différence entre les types de paiement session et intent ?
Une session crée une page de paiement Stripe Checkout avec une URL de redirection, idéale pour les pages de paiement hébergées. Une intent crée une intention de paiement pour l'intégration d'un formulaire de paiement personnalisé directement dans votre application.
Puis-je prendre en charge plusieurs méthodes de paiement ?
Oui ! Créez plusieurs comptes de paiement (Stripe, personnalisé, paiement à la livraison) dans le panneau d'administration. Chaque commande peut utiliser un compte de paiement différent en fonction de la sélection du client.
Comment lier les statuts de paiement aux statuts de commande ?
Dans le panneau d'administration, allez à Payments > Statuses, sélectionnez votre stockage de commandes, et mappez les quatre statuts de paiement prédéfinis (En attente, Payé, Annulé, Expiré) aux statuts de commande correspondants. Cela permet une synchronisation automatique.
Que se passe-t-il si une session de paiement expire ?
Les sessions de paiement ont une durée de vie configurable (définie dans les paramètres du compte). Si un client ne termine pas le paiement dans ce délai, le statut de la session change en "Expiré" et il devra créer une nouvelle session de paiement.
🎓 Meilleures Pratiques
- Utilisez la tokenisation - Tokenisez toujours les cartes avec Stripe.js
- Validez les montants - Vérifiez les totaux sur le serveur, pas seulement côté client
- Gérez les erreurs avec grâce - Messages d'erreur clairs pour les utilisateurs
- Enregistrez les transactions - Conservez une trace d'audit de tous les paiements
- Utilisez des webhooks - Écoutez les mises à jour de statut de paiement
- Testez avec des clés de test - Utilisez le mode test de Stripe avant la production
- Gérez 3D Secure - Implémentez le flux d'authentification SCA
- Conservez les ID de transaction - Gardez des références de passerelle pour les litiges
Définition du module Payments
Le module Payments gère le traitement des paiements et les transactions. Il fournit des outils pour travailler avec des comptes de paiement, créer des sessions de paiement et suivre les statuts de paiement.
const { Payments } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentation Connexe
- Panneau d'Administration OneEntry - Payments - Documentation officielle du panneau d'administration
- Panneau d'Administration OneEntry - Comptes de Paiement - Configurez les comptes de paiement
- Panneau d'Administration OneEntry - Statuts de Paiement - Synchronisation des statuts
- Panneau d'Administration OneEntry - Intégration Stripe - Connectez Stripe
- Module Orders - Gestion des commandes et paiement
- Module AuthProvider - Nécessaire pour l'autorisation de session
- Module Products - Produits disponibles à l'achat
- Documentation Stripe - Intégration de la passerelle de paiement