Plugin de Odoo

El proveedor de pagos Genius Checkout para Odoo añade Genius Checkout como opción nativa en el módulo de Pagos de Odoo. Soporta checkout hospedado de tarjeta, reembolsos parciales y totales desde las pantallas de contabilidad, tarjetas guardadas vía tokenización, y Odoo Subscriptions a través de transacciones merchant-initiated.

Requisitos

• Odoo 17.0, 18.0 o 19.0 (Community o Enterprise). Un backport a 16.0 es directo — ver "Odoo 16 backport".
• Una cuenta Genius Checkout con la integración Odoo activa en Merchant → Connected Apps.

Instalación

Paso 1 — conecta primero en GC

Haz esto antes de instalar el módulo Odoo para tener tu webhook secret a la mano:

1. Inicia sesión en https://app.geniuscheckout.com.
2. Connected Apps → Connect Odoo.
3. Pega tu URL de Odoo + tu Odoo personal API key.
4. GC mostrará un webhook secret de una sola vez — cópialo ahora.

Paso 2 — instala el módulo en Odoo

1. Copia la carpeta del módulo en el path addons de Odoo como payment_geniuscheckout (o usa el import de branch GitHub de odoo.sh).
2. Reinicia Odoo y actualiza la lista de apps.
3. Apps → busca "Genius Checkout" → Instalar.

Paso 3 — configura el proveedor

Accounting → Configuration → Payment Providers → Genius Checkout:

Ajuste	Valor
API Key	Tu gc_test_… o gc_live_… (el prefijo controla qué entorno se usa)
Webhook Secret	El valor que copiaste del panel GC en el paso 1
State	Test Mode (validando) o Enabled (live)

Flujo de checkout

1. El cliente llega al checkout de Odoo, elige Tarjeta (el método GC).
2. El proveedor crea una sesión vía POST /api/v1/checkout-sessions y redirige al checkout hospedado de GC.
3. El cliente completa el pago (3DS por GC).
4. Asincrónicamente, GC empuja el evento a /payment/geniuscheckout/webhook. El receiver verifica HMAC-SHA256 sobre {timestamp}.{body} y transiciona la payment transaction.
5. El return browser-side en /payment/geniuscheckout/return re-consulta la sesión GC por id y confía solo en el estado de la API (rechaza tampering de URL de retorno).

Funcionalidades soportadas

Capacidad	Estado
Reembolsos (total + parcial)	Sí — Odoo 17 verificado live
Tokenización	Sí — los clientes pueden guardar tarjeta al pagar
Tarjetas guardadas	Sí — reuso one-click en pedidos subsiguientes
Suscripciones	Sí — funciona con Odoo Subscriptions; facturación recurrente vía /api/v1/payments con semántica MIT
Auth HMAC en webhooks	Sí — {timestamp}.{body}, hex, secret por instancia
i18n	Sí — strings traducidos; help text alineado con archivos PO

Suscripciones

Si sale_subscription está instalado, GC aparece automáticamente como proveedor para productos suscripción. La primera venta captura la tarjeta y la tokeniza; las facturas subsiguientes se cobran silenciosamente vía _send_payment_request — sin redirección.

Reembolsos

Desde una orden o factura confirmada:

1. Abre la Payment Transaction relacionada.
2. Haz clic en Refund (acción estándar de Odoo — surge automáticamente cuando support_refund='partial' está en el proveedor).
3. Ingresa un monto (≤ original) o deja vacío para reembolso total.
4. Odoo crea una refund transaction; el módulo envía a POST /api/v1/payments/{id}/refund y refleja el estado.

Endpoints

Ruta	Dirección	Propósito
/payment/geniuscheckout/return	entrante (navegador)	Cliente vuelve del checkout GC
/payment/geniuscheckout/webhook	entrante (S2S)	Eventos transaccionales server-to-server

Seguridad de webhooks

• HMAC-SHA256 sobre {timestamp}.{body} (hex) en X-GC-Signature.
• Ventana de repetición de 5 minutos sobre X-GC-Timestamp.
• El receptor rechaza proveedores cuyo secret configurado esté vacío o tenga menos de 16 caracteres.

Backport a Odoo 16

Reemplaza la extensión de selección support_refund con support_refund_partial y ajusta la firma de _get_specific_rendering_values (Odoo 16 usó una forma distinta de processing-values). Todo lo demás porta limpio.

Solución de problemas

• Orden queda en draft tras el pago — confirma que la URL del webhook coincida con tu hostname público; revisa el log de Odoo por fallas de verificación HMAC.
• La URL /return no avanza la orden — es intencional: el return browser-side re-consulta la sesión GC y confía solo en el estado de la API, así que una URL alterada queda en draft. Espera al webhook (normalmente segundos).
• Icono genérico del proveedor — limpia la caché estática de Odoo; el icono está en static/description/icon.png y se cablea en data/payment_provider_data.xml.

Soporte

• Issues del módulo: github.com/geniuscheckout/odoo-module/issues
• Soporte GC: [email protected]