# Modèle de passerelle Le modèle de passerelle fournit un point de départ pour créer votre propre passerelle de paiement réservée au PDV. Il génère une extension WordPress fonctionnelle avec un seul fichier PHP, que vous pouvez installer et personnaliser selon vos besoins. ## Fonctionnalités[​](#features "Lien direct vers Fonctionnalités") #### Code minimal Un seul fichier PHP avec uniquement l’essentiel — facile à lire et à modifier #### PDV uniquement Désactivée par défaut sur le paiement web, activée dans les réglages WCPOS #### Configuration automatisée Un script shell gère pour vous tous les remplacements d’espaces réservés #### Versions GitHub Envoyez une montée de version et GitHub Actions génère un ZIP téléchargeable ## Bien démarrer[​](#getting-started "Lien direct vers Bien démarrer") 1 #### Cloner le dépôt de modèle ``` git clone https://github.com/wcpos/woocommerce-gateway-template.git cd woocommerce-gateway-template ``` Vous pouvez aussi cliquer sur le bouton **Utiliser ce modèle** dans le [dépôt GitHub](https://github.com/wcpos/woocommerce-gateway-template) pour créer votre propre copie. 2 #### Exécuter le script de configuration ``` ./create-gateway.sh ``` Le script demande quelques informations — le nom de votre passerelle, une courte description et votre nom d’utilisateur GitHub — puis génère une extension prête à l’emploi dans le répertoire de votre choix. 3 #### Installer l’extension Deux options sont possibles : **Option A — Copier directement le dossier** (si vous avez accès au serveur) : Copiez le dossier de passerelle généré dans le répertoire `wp-content/plugins/` de votre site. **Option B — Compresser en ZIP et téléverser** (la plus simple pour la plupart des utilisateurs) : 1. Compressez le dossier généré dans un fichier `.zip` 2. Dans WordPress, accédez à **Extensions > Ajouter une extension > Téléverser une extension** 3. Choisissez le fichier ZIP et cliquez sur **Installer maintenant** 4 #### Activer dans WCPOS 1. Accédez à **WP Admin > WCPOS > Paramètres > Validation de commande** 2. Recherchez votre nouvelle passerelle dans la liste et activez-la note La passerelle est désactivée par défaut sur la page de validation de commande web standard. WCPOS contrôle les passerelles qui apparaissent dans le PDV via ses propres paramètres. ## Configuration manuelle[​](#manual-setup "Lien direct vers Configuration manuelle") Si vous préférez ne pas utiliser le script, vous pouvez remplacer vous-même les espaces réservés. Ouvrez chaque fichier dans un éditeur de texte, puis recherchez et remplacez les éléments suivants : | Espace réservé | Valeur à saisir | Exemple | | --------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- | | `{{GATEWAY_NAME}}` | Le nom d’affichage de votre passerelle | Paiement en espèces | | `{{GATEWAY_SLUG}}` | Identifiant compatible avec les URL (minuscules, traits d'union) | paiement-especes | | `{{GATEWAY_DESCRIPTION}}` | Brève description de la passerelle | Accepter les paiements en espèces dans WCPOS | | `{{GATEWAY_DEFAULT_DESCRIPTION}}` | Texte affiché au caissier lors du paiement | Payer en espèces au point de vente | | `{{GITHUB_USERNAME}}` | Votre nom d'utilisateur GitHub | jean-dupont | | `{{REPO_NAME}}` | Le nom de votre dépôt | passerelle-paiement-especes | | `{{AUTHOR_NAME}}` | Votre nom | Jean Dupont | | `{{GATEWAY_ID}}` | Slug avec des traits de soulignement à la place des traits d'union | paiement\_especes | | `{{GATEWAY_CLASS_NAME}}` | Chaque mot avec une majuscule initiale, relié par des traits de soulignement | Paiement\_Especes | | `{{GATEWAY_FUNCTION_PREFIX}}` | Identique à l'ID de la passerelle | paiement\_especes | Renommez ensuite `wcpos-{{GATEWAY_SLUG}}.php` pour qu'il corresponde à votre slug (par exemple, `wcpos-cash-payment.php`). astuce Le script de configuration déduit automatiquement `GATEWAY_ID`, `GATEWAY_CLASS_NAME` et `GATEWAY_FUNCTION_PREFIX` à partir du nom et du slug, vous n'avez donc à vous en préoccuper que lors d'une configuration manuelle. ## Fonctionnement[​](#how-it-works "Lien direct vers Fonctionnement") L’extension générée enregistre une classe de passerelle de paiement WooCommerce. Voici les points essentiels à connaître : * **`$this->enabled = 'no'`** — La passerelle est masquée lors du paiement sur le web. WCPOS l’active dans le PDV selon les réglages de votre PDV. * **`process_payment()`** — Appelle `$order->payment_complete()`, ce qui marque la commande comme payée et gère automatiquement la réduction du stock. * **`init_form_fields()`** — Définit les champs Titre et Description qui apparaissent dans les réglages WooCommerce. ## Personnalisation de votre passerelle[​](#customising-your-gateway "Lien direct vers Personnalisation de votre passerelle") ### Ajout de champs de paiement[​](#adding-payment-fields "Lien direct vers Ajout de champs de paiement") Si votre passerelle nécessite une saisie de la part du caissier (par exemple, un numéro de référence), surchargez la méthode `payment_fields()` : ``` public function payment_fields() { if ( $this->description ) { echo wpautop( wptexturize( $this->description ) ); } woocommerce_form_field( 'my_gateway_reference', array( 'type' => 'text', 'label' => __( 'Reference Number', 'your-text-domain' ), 'required' => true, ) ); } ``` Vous pouvez ensuite lire la valeur envoyée dans `process_payment()` via `$_POST['my_gateway_reference']`. Pensez à nettoyer toute saisie avec `sanitize_text_field()`. ### Modification du comportement du paiement[​](#changing-payment-behaviour "Lien direct vers Modification du comportement du paiement") Le modèle par défaut marque les commandes comme payées immédiatement. Si votre flux de travail exige un paiement ultérieur (comme pour une facture), remplacez `payment_complete()` par une mise à jour d’état : ``` public function process_payment( $order_id ) { $order = wc_get_order( $order_id ); // Set to pending — the customer will pay later. $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) ); // Stock must be reduced manually when not using payment_complete(). wc_reduce_stock_levels( $order_id ); return array( 'result' => 'success', 'redirect' => $this->get_return_url( $order ), ); } ``` ## Apporter des modifications et effectuer des mises à jour[​](#making-changes-and-updating "Lien direct vers Apporter des modifications et effectuer des mises à jour") Après l’installation de votre passerelle, vous pouvez continuer à modifier le fichier de l’extension pour ajuster la logique de paiement. Pour installer une version mise à jour : 1. Modifiez `wcpos-your-slug.php` dans le dossier généré 2. Mettez à jour le numéro `Version:` dans l’en-tête de l’extension (par exemple, de `0.1.0` à `0.2.0`) 3. Compressez le dossier au format zip et téléversez-le à nouveau via **Extensions > Ajouter une extension > Téléverser une extension**, ou remplacez directement le dossier dans `wp-content/plugins/` astuce WordPress vous demandera si vous souhaitez remplacer l’extension existante lorsque vous téléversez un fichier zip portant le même nom d’extension — cliquez sur **Remplacer l’extension actuelle par celle téléversée** pour la mettre à jour. ### Versions automatisées avec GitHub[​](#automated-releases-with-github "Lien direct vers Versions automatisées avec GitHub") Si vous poussez votre passerelle vers un dépôt GitHub, le modèle inclut un workflow GitHub Actions qui crée automatiquement des versions : 1. Mettez à jour le numéro `Version:` dans l’en-tête de l’extension 2. Effectuez un commit et poussez vers la branche `main` 3. GitHub Actions détecte le changement de version et crée une nouvelle version avec un fichier ZIP téléchargeable Les autres utilisateurs peuvent ensuite télécharger le fichier ZIP depuis la page **Versions** de votre dépôt et l’installer comme n’importe quelle extension WordPress. ## Dépannage[​](#troubleshooting "Lien direct vers Dépannage") La passerelle n’apparaît pas dans le PDV * Vérifiez que l’extension est activée dans **WP Admin > Extensions** * Accédez à **WP Admin > WCPOS > Réglages > Paiement** et assurez-vous que la passerelle est activée * Vérifiez que WooCommerce est installé et actif La passerelle apparaît sur la page de paiement web * Assurez-vous que `$this->enabled = 'no';` est défini dans le constructeur de la passerelle * WCPOS remplace ce réglage pour les requêtes du PDV, la passerelle ne devrait donc apparaître que dans le PDV Les commandes restent à l’état « En cours » au lieu de « Terminée » * WooCommerce définit l’état de la commande en fonction des types de produits. Les commandes contenant des produits physiques restent à l’état "En cours" — il s’agit du comportement normal de WooCommerce. Seules les commandes contenant exclusivement des produits virtuels ou téléchargeables sont automatiquement marquées comme "Terminée". ## Prérequis[​](#requirements "Lien direct vers Prérequis") WCPOS : Version Pro requise pour le passage en caisse du PDV WordPress : WordPress avec WooCommerce installé PHP : Connaissances de base en PHP pour personnaliser la passerelle ## Ressources[​](#resources "Lien direct vers Ressources") * **GitHub** : [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template) * **API de passerelle de paiement WooCommerce** : [documentation WC\_Payment\_Gateway](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html) ### Exemples de passerelles[​](#example-gateways "Lien direct vers Exemples de passerelles") Ces passerelles existantes ont été créées selon la même approche et constituent de bonnes références : * **[Facture par e-mail](/fr/payment/gateways/email-invoice.md)** — Envoie une facture par e-mail afin que le client puisse payer plus tard * **[Paiement en ligne](/fr/payment/gateways/web-checkout.md)** — Redirige vers la boutique en ligne pour le paiement