Plugin Magento 2

Le module Genius Checkout pour Magento 2 ajoute Genius Checkout comme moyen de paiement, avec configuration admin, un renderer Knockout dans le checkout, un sélecteur de cartes enregistrées pour les clients connectés, et la gestion des remboursements via le flux credit memo standard de Magento.

Installation

composer require geniuscheckout/magento2
bin/magento module:enable GeniusCheckout_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Configurer

Admin → Stores → Configuration → Sales → Payment Methods → Genius Checkout :

Réglage	Valeur
Enabled	Yes
API Key	Votre clé gc_test_… ou gc_live_… (champ admin, chiffré au repos)
Webhook Secret	Même valeur que dans Tableau de bord GC → Developers → Webhooks
Test Mode	Yes jusqu'à la mise en production
New Order Status	Statut après autorisation du paiement
Sort Order	Position dans la liste de moyens de paiement

URL webhook :

https://votre-magento.example.com/geniuscheckout/index/webhook

Abonnez à : payment.completed, payment.failed, payment.refunded, payment.voided.

Flux de checkout

1. L'acheteur arrive au checkout Magento, choisit Genius Checkout.
2. Au place-order, le mixin place-order redirige l'acheteur vers le checkout hébergé GC.
3. L'acheteur complète le paiement ; GC POST payment.completed au récepteur, qui passe la commande au statut configuré.

Cartes enregistrées (clients connectés)

Pour les clients connectés, le renderer affiche une liste radio des cartes précédemment enregistrées, via le proxy server-side /geniuscheckout/index/savedcards :

• Le proxy transfère l'appel à GET /api/v1/customers/{external_customer_id}/payment-tokens avec la clé API du marchand — la clé n'atteint jamais le navigateur.
• Le proxy utilise Authorization: Bearer ….
• Seul {id, brand, last4, expiry_month, expiry_year} est exposé à la page.
• Sélectionner une carte enregistrée renseigne additional_data.payment_token_id sur le payload place-order pour débiter directement le token (sans redirection). Sélectionner "Use a new card" retombe sur le flux hébergé.

Fonctionnalités supportées

Capacité	Statut
Remboursements via credit memo	Oui
Tokenisation	Oui
Sélecteur de cartes enregistrées	Oui (clients connectés ; "Use a new card" retombe sur l'hébergé)
Abonnements	Pas nativement en Magento CE (nécessite Adobe Commerce ou une extension recurring tierce)
i18n	Oui — CSVs en_US, fr_FR, es_ES, pt_BR

Remboursements

Depuis la page de commande admin → Credit Memo → Refund. Magento appelle le refund() du module qui POST vers POST /api/v1/payments/{id}/refund. Une clé d'idempotency liée à l'ID payment entity Magento + montant empêche les doubles remboursements en cas de re-soumission.

Sécurité webhook

Le contrôleur webhook s'authentifie via HMAC-SHA256 (X-GC-Signature sur {timestamp}.{body}, fenêtre de 5 minutes) et déclare CsrfAwareActionInterface::validateForCsrf → true car il n'a pas besoin du token CSRF de Magento (la signature est le mécanisme d'auth).

Dépannage

• Méthode absente de la liste de checkout — confirmez "Enabled" Yes et que le pays de facturation du client n'est pas bloqué sous Sales → Payment Methods → Genius Checkout → Allowed Countries.
• Liste cartes enregistrées vide pour un client connecté — vérifiez que l'ID client storefront est mappé côté GC (le proxy utilise customer.entity_id) ; un acheteur neuf voit [] jusqu'à son premier checkout.
• Logo non rendu — Model/ConfigProvider::logo_url retombe sur AssetRepository::getUrl('GeniusCheckout_Payment::images/genius-checkout-logo.svg'). Videz le cache static-content : bin/magento cache:flush && bin/magento setup:static-content:deploy.
• No gateway configuration found for this merchant — assurez-vous qu'une passerelle est connectée dans votre tableau de bord GC pour le mode actif (test vs live).