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

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

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 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

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

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

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

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

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

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

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

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

• GitHub : woocommerce-gateway-template
• API de passerelle de paiement WooCommerce : documentation WC_Payment_Gateway

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 — Envoie une facture par e-mail afin que le client puisse payer plus tard
• Paiement en ligne — Redirige vers la boutique en ligne pour le paiement