Introduction

🎯 Que fait ce module ?

Le module Payments vous permet de gérer le traitement des paiements et des transactions pour votre boutique en ligne. Travailler avec les paiements et les transactions est une partie importante de tout projet de commerce électronique. 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 de OneEntry (Payments > Accounts), créez plusieurs comptes pour différents types de paiements, comme 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 de commerce électronique 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 - Suivre les paiements en attente, complétés, échoués, remboursés
• 💰 Remboursements - Traiter les remboursements complets ou partiels
• 📊 Historique des paiements - Voir toutes les transactions
• 🔗 Intégration de passerelle - 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	Connecter 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. Créer un compte de paiement dans le panneau d'administration
   (Configurer le compte Stripe ou personnalisé)
   ↓
2. Le client passe une commande
   (Commande créée dans le module Orders)
   ↓
3. Créer une session de paiement
   (Payments.createSession(orderId, type))
   ↓
4. Le client est redirigé vers l'URL de paiement
   (Checkout Stripe ou page de paiement personnalisée)
   ↓
5. Le client complète le paiement
   (Paiement traité par la passerelle)
   ↓
6. Statut du paiement mis à jour
   (en attente → en cours → payé/annulé/expiré)
   ↓
7. Notification reçue
   ↓
8. Statut de la commande synchronisé
   (Statut de paiement lié au statut de commande)

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 réussie	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 des paiements sécurisés 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 d'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 de OneEntry :

Panneau d'administration OneEntry → Payments → Accounts → Créer un compte → Remplir le formulaire → Cliquer sur "Ajouter"

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/le type/le token/les 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 d'expiration de la session en minutes

Synchronisation des statuts de paiement

Les statuts de paiement peuvent être liés aux statuts de stockage des commandes :

Panneau d'administration OneEntry → Payments → Statuses → Sélectionner le stockage des commandes → Mapper les statuts → Enregistrer

Flux de travail de mappage des statuts :

1. Accédez à la sous-section Statuts dans Payments
2. Sélectionnez le système de stockage des commandes souhaité
3. Mappez chaque statut de paiement prédéfini à la valeur de statut de stockage des commandes correspondante
4. Vérifiez que tous les mappages sont exacts
5. 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, le CVV ou les 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 :

1. Accédez à Payments > Accounts
2. Remplissez le formulaire avec le Nom, le Type et le Token
3. Pour les comptes Stripe, configurez l'URL de succès, l'URL d'annulation et la durée de session
4. Cliquez sur "Ajouter" pour créer

Gestion des comptes :

• Modifier - 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 :

1. Accédez à Payments > Statuses
2. Sélectionnez le système de stockage des commandes
3. Mappez les statuts de paiement prédéfinis aux statuts de stockage des commandes
4. 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 sessions

Deux types de sessions 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()	Obtenir tous les comptes de paiement	Lister les méthodes de paiement disponibles
getAccountById()	Obtenir un compte de paiement par ID	Récupérer les détails d'un compte spécifique
createSession() 🔐	Créer une session de paiement	Générer un lien de paiement pour la commande
getSessions() 🔐	Obtenir toutes les sessions de paiement (paginé)	Voir l'historique des sessions de paiement
getSessionById() 🔐	Obtenir une session de paiement par ID	Vérifier le statut d'une session spécifique
getSessionByOrderId() 🔐	Obtenir une session de paiement par ID de commande	Trouver 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 complète 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 - Toujours tokeniser 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 le 3D Secure - Implémentez le flux d'authentification SCA
• Conservez les ID de transaction - Gardez les références de passerelle pour les litiges

---

Plus d'informations sur les paiements dans le panneau d'administration de OneEntry : https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/payments

---

Définition du module Payments

Le module Payments gère le traitement des paiements et des 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 - Configurer les comptes de paiement
• Panneau d'administration OneEntry - Statuts de paiement - Synchronisation des statuts
• Panneau d'administration OneEntry - Intégration Stripe - Connecter 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

---