Passer au contenu principal
Version : 1.x

Modèle de Passerelle

Le Modèle de Passerelle WooCommerce fournit un point de départ pour créer vos propres passerelles de paiement personnalisées pour WooCommerce POS. Ce modèle comprend tout le code de base nécessaire et la structure pour construire une passerelle de paiement entièrement fonctionnelle.

Fonctionnalités​

Modèle Complet

Structure de passerelle prête à l'emploi avec toutes les méthodes requises

Intégration POS

Préconfiguré pour la compatibilité avec WooCommerce POS

Configuration Automatisée

Personnalisation du modèle basée sur un script

Extensible

Facile à modifier et à étendre pour des fournisseurs de paiement spécifiques

Prise en Main​

Option 1 : Génération Automatisée du Modèle​

Le modèle inclut un script qui automatise la personnalisation du modèle pour votre passerelle spécifique :

  1. Cloner le Dépôt :

    git clone https://github.com/wcpos/woocommerce-gateway-template.git
    cd woocommerce-gateway-template

  2. Exécuter le Script de Configuration :

    ./create-gateway.sh

  3. Suivre les Instructions :

    • Entrez le nom de votre passerelle (ex. : "Ma Passerelle de Paiement")
    • Entrez un slug de passerelle (ex. : "ma-passerelle")
    • Fournissez une description
    • Le script générera un plugin personnalisé

Option 2 : Utilisation Manuelle du Modèle​

Si vous préférez une personnalisation manuelle :

  1. Télécharger le Modèle :

  2. Personnaliser le Modèle :

    • Remplacez {{GATEWAY_NAME}} par le nom affiché de votre passerelle
    • Remplacez {{GATEWAY_SLUG}} par l'identifiant unique de votre passerelle
    • Remplacez {{GATEWAY_DESCRIPTION}} par la description de votre passerelle

  3. Renommer les Fichiers :

    • Renommez wcpos-{{GATEWAY_SLUG}}.php pour qu'il corresponde au slug de votre passerelle
    • Mettez à jour les en-têtes de fichiers et les informations sur le plugin

Structure du Modèle​

Fichier Principal du Plugin​

Le fichier principal du plugin (wcpos-{{GATEWAY_SLUG}}.php) contient :

  • Entête du Plugin : Informations sur le plugin WordPress
  • Classe de Passerelle : Classe principale de la passerelle de paiement
  • Initialisation : Configuration du plugin et hooks
  • Intégration : Compatibilité avec WooCommerce POS

Composants Clés​

Structure de la Classe de Passerelle :

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

Guide de Personnalisation​

Configuration de Base​

  1. Informations sur la Passerelle :

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. Fonctionnalités Prises en Charge :

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

Traitement des Paiements​

La logique principale du paiement se trouve dans la méthode process_payment() :

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

Paramètres Administratifs​

Configurez les paramètres administratifs dans init_form_fields() :

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

Intégration POS​

Pour une fonctionnalité spécifique à POS, implémentez :

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

Meilleures Pratiques de Développement​

Normes de Codage​

  • Normes de Codage WordPress : Suivez les normes de codage PHP de WordPress
  • Directives WooCommerce : Respectez les pratiques de développement de WooCommerce
  • Sécurité : Assainir les entrées, valider les données, utiliser des nonces
  • Internationalisation : Rendez les chaînes traduisibles en utilisant __() et _e()

Gestion des Erreurs​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

Journalisation​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

Tester Votre Passerelle​

Environnement de Développement​

  1. Mode Test : Toujours mettre en oeuvre un mode test/sandbox
  2. Journalisation de Débogage : Inclure une journalisation complète pour le dépannage
  3. Scénarios d'Erreur : Tester diverses conditions d'échec
  4. Tests POS : Tester spécifiquement dans l'environnement POS

Cas de Test​

  • Paiements Réussis : Vérifier que les commandes se complètent correctement
  • Paiements Échoués : Assurer une gestion appropriée des erreurs
  • Remboursements : Tester la fonctionnalité de remboursement si prise en charge
  • Cas Limites : Tester avec divers montants de commandes et configurations

Déploiement​

Pack d'Plugins​

  1. Supprimer les Fichiers de Développement : Nettoyer les fichiers de test et les outils de développement
  2. Contrôle de Version : Mettre à jour les numéros de version dans l'en-tête du plugin
  3. Documentation : Inclure README avec les instructions d'installation
  4. Package Zip : Créer un fichier zip installable

Distribution​

  • Versions GitHub : Utiliser les versions GitHub pour la gestion des versions
  • Répertoire des Plugins WordPress : Envisager de soumettre à WordPress.org
  • Distribution Privée : Héberger sur vos propres serveurs si besoin

Fonctionnalités Avancées​

Webhooks​

Pour des mises à jour de paiement en temps réel :

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

Support des Abonnements​

Pour des paiements récurrents :

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

Multi-devises​

Pour des paiements internationaux :

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

Ressources​

Documentation​

Dépôt du Modèle​

  • GitHub : woocommerce-gateway-template
  • Issues : Signaler des problèmes de modèle ou demander des fonctionnalités
  • Contributions : Soumettre des améliorations via des pull requests

Obtenir de l'Aide​

Pour le support de développement :

  • Visitez le dépôt GitHub pour des problèmes spécifiques au modèle
  • Consultez la documentation des développeurs WooCommerce pour des questions sur l'API
  • Rejoignez la communauté des développeurs WooCommerce pour des conseils généraux

Passerelles d'Exemple​

Étudiez ces passerelles personnalisées existantes pour des exemples d'implémentation :