Plugin de Wix (Velo)

La integración con Wix es un starter SDK de Velo Service Plugin — colócalo en el backend Velo de un comercio Wix Studio para aceptar pagos Genius Checkout a través de la superficie Custom Payments de Wix. Esta ruta es autoservicio — no requiere revisión de Wix App Market.

Dos rutas de integración

Wix expone el contrato Payment Provider de dos formas:

Ruta	Objetivo	Aprobación	Cuándo usar
REST app	App Wix App Market (endpoints server)	Programa Partner + revisión 2-6 semanas	Un procesador vendiendo a muchos comercios Wix
Velo Service Plugin (este plugin)	Backend Velo de un solo comercio	Autoservicio, inmediato	Un comercio que ya tiene Wix Velo en su plan

Si eres un solo comercio, usa el plugin Velo. Si procesas para muchos comercios, contáctanos sobre la REST app.

Instalar (5 minutos)

1. Abre el panel Velo Service Plugin. En Wix Studio → Develop → Service Plugins → Add a Service Plugin → elige Payments → Wix Payments Provider.
2. Copia backend/payment-provider-spi.js del starter GC al archivo que Wix generó (Wix auto-crea el nombre correcto bajo backend/service-plugins/wix-payments/payment-provider/).
3. Agrega dos secretos en Secrets Manager:
   • gcApiKey — copia de https://app.geniuscheckout.com/merchant/api-keys (usa gc_test_… mientras pruebas, gc_live_… después).
   • gcReturnUrlBase — https://app.geniuscheckout.com (deja por defecto salvo en una región GC dedicada).
4. Publica el backend Velo.

El plugin ahora aparece como Custom payments → Genius Checkout en Wix → Settings → Accept Payments.

Configurar en el panel GC

En el panel GC, configura la URL del webhook a la URL que Wix generó para el backend Velo (Wix la expone bajo el panel del Payments service-plugin como "webhook URL"). Suscribe a: payment.completed, payment.failed, payment.refunded.

Flujo de checkout

1. El comprador llega al checkout de Wix, elige Genius Checkout.
2. Wix llama al createTransaction(...) del plugin Velo que hace POST a /api/v1/checkout-sessions y devuelve el checkout_url hospedado.
3. El comprador completa el pago en la página hospedada de GC.
4. El sitio Wix recibe la actualización de estado asíncrona; el comprador es devuelto a Wix con el estado final (approved o declined).

Funcionalidades soportadas

Capacidad	Estado
Reembolsos	Sí — Wix llama refundTransaction(...) que pega a POST /api/v1/payments/{id}/refund
Tokenización	Tokens en la plataforma GC; Wix no expone picker de tarjetas guardadas vía el contrato Service Plugin
Suscripciones	No vía Velo Service Plugin — usa Recurring Plans de Wix + la API de Suscripciones de GC si necesitas facturación recurrente
Unidades menores con monedas	Sí — manejado en el REST controller; el plugin pasa currencyCode de Wix sin cambios

Notas de arquitectura

El plugin Velo usa los mismos endpoints /api/v1/checkout-sessions y /api/v1/payments/{id}/refund que los módulos WC, Give, Odoo, PrestaShop, Magento y OpenCart. Todos están e2e-tested live (ver storefront-plugins/AUDIT-2026-05-13.md). El archivo Velo no está e2e-tested por sí mismo porque requiere un sitio Wix Studio real — el comercio lo ejecuta.

Referencia

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

Solución de problemas

• Método no aparece en el checkout de Wix — confirma que el plugin Velo esté Publicado (los drafts no se propagan); el plan Wix del comercio debe incluir Velo.
• gcApiKey no definido — revisa Secrets Manager; los nombres son sensibles a mayúsculas.
• 422 al crear sesión — verifica que la moneda del carrito esté en la lista soportada; el plugin pasa el currencyCode de Wix directo a GC.