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.

Caractéristiques​

  • 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
  • Meilleures Pratiques : Suit les normes de codage de WordPress et WooCommerce
  • Extensible : Facile à modifier et à étendre pour des fournisseurs de paiement spécifiques

Prise en Main​

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

Le modèle comprend un script qui personnalise automatiquement le modèle pour votre passerelle spécifique :

  1. Clonez le Dépôt :

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

  2. Exécutez le Script de Configuration :

    ./create-gateway.sh

  3. Suivez les Invites :

    • Entrez le nom de votre passerelle (par exemple, "Ma Passerelle de Paiement")
    • Entrez un slug de passerelle (par exemple, "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échargez le Modèle :

  2. Personnalisez le Modèle :

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

  3. Renommez les Fichiers :

    • Renommez wcpos-{{GATEWAY_SLUG}}.php pour correspondre à votre slug de passerelle
    • Mettez à jour les en-têtes de fichier et les informations sur le plugin

Structure du Modèle​

Fichier Principal du Plugin​

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

  • En-tê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 de paiement principale va 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 Admin​

Configurez les paramètres admin 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 la fonctionnalité spécifique au 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 Code​

  • 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 : Rendre 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 : Implémentez toujours un mode test/sandbox
  2. Journalisation de Débogage : Incluez une journalisation complète pour le dépannage
  3. Scénarios d'Erreur : Testez diverses conditions d'échec
  4. Tests POS : Testez spécifiquement dans l'environnement POS

Cas de Test​

  • Paiements Réussis : Vérifiez que les commandes se complètent correctement
  • Paiements Échoués : Assurez-vous de la bonne gestion des erreurs
  • Remboursements : Testez la fonctionnalité de remboursement si supportée
  • Cas Extrêmes : Testez avec divers montants de commande et configurations

Déploiement​

Emballage du Plugin​

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

Distribution​

  • Versions GitHub : Utilisez les versions GitHub pour la gestion des versions
  • Répertoire des Plugins WordPress : Envisagez de soumettre à WordPress.org
  • Distribution Privée : Hébergez sur vos propres serveurs si nécessaire

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 les paiements récurrents :

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

Multi-devises​

Pour les paiements internationaux :

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

Ressources​

Documentation​

Dépôt de Modèle​

  • GitHub : woocommerce-gateway-template
  • Problèmes : Signalez des problèmes de modèle ou demandez des fonctionnalités
  • Contributions : Soumettez des améliorations via des demandes de tirage

Obtenir de l'Aide​

Pour un soutien en 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 Exemples​

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