Aller au contenu principal

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 créer des sessions de paiement et de suivre les transactions pour votre boutique. Vous configurez les comptes de paiement dans le panneau d'administration (Payments > Accounts) — Stripe ou personnalisé — et ce module crée une session de paiement pour une commande, renvoie le lien de paiement de la passerelle et vous permet de lire l'historique et le statut de la session.

Le SDK récupère les comptes de paiement et crée des sessions de paiement ; les comptes et les statuts sont configurés dans le panneau d'administration.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Créez une session de paiement pour une commande et redirigez le client vers la passerelle (auth requis) :

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Concepts clés​

Qu'est-ce qu'une session de paiement ?​

Une session de paiement (ISessionEntity) est un enregistrement contenant :

  • type — 'session' ou 'intent'
  • status — chaîne de statut de paiement libre (par exemple, "waiting", "completed")
  • paymentAccountId — le compte configuré utilisé
  • orderId — la commande associée
  • paymentUrl — lien de paiement de la passerelle (ou null)
  • createdDate / updatedDate — horodatages

Types de session​

TypeDescription
sessionCrée une page de paiement Stripe Checkout avec un lien de paiement redirigé
intentCrée une intention de paiement pour un traitement de paiement direct/personnalisé

Types de compte​

TypeQuand l'utiliserConfiguration requise
StripeConnectez le système de paiement StripeCompte Stripe, URLs
CustomSystèmes de paiement alternatifs ou paiements en espècesConfiguration personnalisée

Statuts de paiement​

Le status d'une session est une chaîne libre définie à partir du résultat de la passerelle, pas une énumération fixe. Valeurs courantes :

StatutSignification
waitingSession créée, en attente de paiement
completedPaiement confirmé par la passerelle

Vous ne pouvez pas créer ou modifier les statuts de paiement dans le panneau d'administration. Vous pouvez cependant mapper les statuts de paiement aux statuts de stockage des commandes afin que le statut de la commande se mette à jour automatiquement lorsque le statut de paiement change.

Cycle de vie du paiement​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 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 — créez et modifiez-les dans le panneau d'administration OneEntry (Payments > Accounts), en fournissant Nom, Type (Stripe ou Custom), et Token. Pour les comptes Stripe, vous configurez également Success URL, Cancel URL, et Session lifetime. Le SDK est destiné à récupérer des comptes et créer des sessions.

Synchronisation des statuts​

Les statuts de paiement sont mappés aux statuts de stockage des commandes dans le panneau d'administration (Payments > Statuses → sélectionnez le stockage des commandes → mapper les statuts → enregistrer). Cela permet des mises à jour automatiques du statut de la commande lorsque le statut de paiement change.

Ne jamais stocker de données de carte brutes​

Ne stockez jamais les numéros de carte de crédit, le CVV ou les dates d'expiration complètes. Le paiement est géré par la passerelle (Stripe), ce qui vous maintient hors du champ d'application pour le stockage des données de carte ; OneEntry ne stocke jamais les détails de carte bruts.

Les remboursements se trouvent dans le module Orders​

Le module Payments n'a aucune méthode de remboursement. Les remboursements sont gérés par le module Orders via createRefundRequest(), cancelRefundRequest(), et getRefunds().

📊 Tableau de référence rapide​

MéthodeDescriptionCas d'utilisation
getAccounts() 🔐Obtenir tous les comptes de paiementLister les comptes de paiement configurés
getAccountById() 🔐Obtenir un compte de paiement par IDRécupérer les détails d'un compte spécifique
createSession() 🔐Créer une session de paiementGénérer un lien de paiement pour une commande
getSessions() 🔐Obtenir toutes les sessions de paiement (paginé)Voir l'historique des sessions de paiement
getSessionById() 🔐Obtenir une session de paiement par IDVérifier le statut d'une session spécifique
getSessionByOrderId() 🔐Obtenir une session de paiement par ID de commandeTrouver le paiement pour une commande spécifique

🔐 = Nécessite une autorisation

❓ Questions fréquentes (FAQ)​

Comment configurer les paiements Stripe ?​

Créez un compte de paiement dans le panneau d'administration avec le type "Stripe", puis configurez Success URL, Cancel URL, et Session lifetime. Utilisez createSession() avec le type "session" pour générer un lien qui redirige 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 comptes de paiement ?​

Oui. Créez plusieurs comptes de paiement (Stripe ou personnalisé) dans le panneau d'administration. Chaque commande peut utiliser un compte différent via son paymentAccountIdentifier.

Comment lier les statuts de paiement aux statuts de commande ?​

Dans le panneau d'administration, allez dans Payments > Statuses, sélectionnez votre stockage de commande, et mappez les statuts de paiement aux statuts de commande. Cela permet une synchronisation automatique.

Comment émettre un remboursement ?​

Les remboursements ne font pas partie du module Payments. Utilisez le module Orders : createRefundRequest() pour demander un remboursement, cancelRefundRequest() pour annuler une demande, et getRefunds() pour les lister.

🎓 Meilleures pratiques​

  • Authentifiez-vous d'abord — chaque méthode Payments nécessite un utilisateur autorisé (voir AuthProvider).
  • Redirigez vers paymentUrl après avoir créé une session, et gérez les URL de retour de la passerelle dans votre application.
  • Lisez le statut de la session, pas du client — vérifiez le status de la session (ou getSessionByOrderId()) pour confirmer le paiement.
  • Mappez les statuts de paiement aux statuts de commande afin que l'état de la commande reste synchronisé automatiquement.
  • Testez avec les clés de test Stripe avant de passer en production.

🔗 Documentation connexe​