Plugin Wix (Velo)

L'intégration Wix est un starter SDK Velo Service Plugin — déposez-le dans le backend Velo d'un marchand Wix Studio pour accepter les paiements Genius Checkout via la surface Custom Payments de Wix. Cette voie est self-service — pas de revue Wix App Market requise.

Deux voies d'intégration

Wix expose le contrat Payment Provider de deux manières :

Voie	Cible	Approbation	Quand l'utiliser
REST app	App Wix App Market (endpoints serveur)	Programme Partner + revue de 2-6 semaines	Un processeur vendant à de nombreux marchands Wix
Velo Service Plugin (ce plugin)	Backend Velo d'un seul marchand	Self-service, immédiat	Un marchand qui a déjà Wix Velo sur son plan

Si vous êtes un seul marchand, utilisez le plugin Velo. Si vous traitez pour de nombreux marchands, contactez-nous à propos de la REST app.

Installer (5 minutes)

1. Ouvrez le panneau Velo Service Plugin. Dans Wix Studio → Develop → Service Plugins → Add a Service Plugin → choisissez Payments → Wix Payments Provider.
2. Copiez backend/payment-provider-spi.js du starter GC dans le fichier que Wix a généré (Wix crée automatiquement le bon nom de fichier sous backend/service-plugins/wix-payments/payment-provider/).
3. Ajoutez deux secrets dans Secrets Manager :
   • gcApiKey — copiez depuis https://app.geniuscheckout.com/merchant/api-keys (utilisez gc_test_… pendant les tests, gc_live_… plus tard).
   • gcReturnUrlBase — https://app.geniuscheckout.com (laissez par défaut sauf région GC dédiée).
4. Publiez le backend Velo.

Le plugin apparaît maintenant comme Custom payments → Genius Checkout dans Wix → Settings → Accept Payments.

Configurer sur le tableau de bord GC

Dans le tableau de bord GC, configurez l'URL webhook Wix sur celle que Wix a générée pour le backend Velo (Wix l'expose sous le panneau du Payments service-plugin comme "webhook URL"). Abonnez à : payment.completed, payment.failed, payment.refunded.

Flux de checkout

1. L'acheteur arrive au checkout Wix, choisit Genius Checkout.
2. Wix appelle le createTransaction(...) du plugin Velo qui POST vers /api/v1/checkout-sessions et renvoie le checkout_url hébergé pour rediriger l'acheteur.
3. L'acheteur complète le paiement sur la page hébergée GC.
4. Le site Wix du marchand reçoit la mise à jour de statut asynchrone ; l'acheteur est renvoyé vers Wix avec le statut final (approved ou declined).

Fonctionnalités supportées

Capacité	Statut
Remboursements	Oui — Wix appelle refundTransaction(...) qui touche POST /api/v1/payments/{id}/refund
Tokenisation	Tokens sur la plateforme GC ; Wix n'expose pas de sélecteur de cartes enregistrées via le contrat Service Plugin
Abonnements	Pas via Velo Service Plugin — utilisez les Recurring Plans natifs de Wix + l'API Abonnements GC si besoin de facturation récurrente
Unités mineures conscientes des devises	Oui — gérées dans le contrôleur REST ; le plugin passe currencyCode de Wix sans modification

Notes d'architecture

Le plugin Velo utilise les mêmes endpoints /api/v1/checkout-sessions et /api/v1/payments/{id}/refund que les modules WC, Give, Odoo, PrestaShop, Magento et OpenCart. Tous sont e2e-testés en live (voir storefront-plugins/AUDIT-2026-05-13.md). Le fichier Velo lui-même n'est pas e2e-testé car il nécessite un vrai site Wix Studio pour l'installer — le marchand le lance.

Référence

• Doc Velo Service Plugin (Wix)
• API Genius Checkout

Dépannage

• Méthode n'apparaît pas dans le checkout Wix — confirmez que le plugin Velo est Publié (les drafts ne se propagent pas) ; le plan Wix du marchand doit inclure Velo.
• gcApiKey non défini — revérifiez Secrets Manager ; les noms de secrets sont sensibles à la casse.
• 422 à la création de session — vérifiez que la devise du panier est dans la liste supportée ; le plugin passe le currencyCode Wix tel quel à GC.