Plugin de Magento 2

El módulo Genius Checkout para Magento 2 añade Genius Checkout como método de pago, con configuración admin, un renderer Knockout en el checkout, un picker de tarjetas guardadas para clientes con sesión iniciada, y manejo de reembolsos vía el flujo estándar de credit memo de Magento.

Instalación

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

Configurar

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

Ajuste	Valor
Enabled	Yes
API Key	Tu clave gc_test_… o gc_live_… (campo admin, cifrado en reposo)
Webhook Secret	Mismo valor que en Panel GC → Developers → Webhooks
Test Mode	Yes hasta producción
New Order Status	Estado a aplicar tras autorización
Sort Order	Posición en la lista de pagos

URL de webhook:

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

Suscribe a: payment.completed, payment.failed, payment.refunded, payment.voided.

Flujo de checkout

1. El comprador llega al checkout de Magento, elige Genius Checkout.
2. Al hacer Place Order, el mixin de place-order redirige al checkout hospedado de GC.
3. El comprador completa el pago; GC hace POST payment.completed al receptor, que mueve la orden al estado configurado.

Tarjetas guardadas (clientes con sesión)

Para clientes con sesión, el renderer muestra una lista radio de tarjetas previamente guardadas, vía el proxy server-side /geniuscheckout/index/savedcards:

• El proxy reenvía la llamada a GET /api/v1/customers/{external_customer_id}/payment-tokens con la API key del comercio — la clave nunca llega al navegador.
• El proxy usa Authorization: Bearer ….
• Solo {id, brand, last4, expiry_month, expiry_year} se expone al navegador.
• Elegir una tarjeta guardada setea additional_data.payment_token_id en el payload de place-order para cobrar el token directo (sin redirección). Elegir "Use a new card" cae al flujo hospedado.

Funcionalidades soportadas

Capacidad	Estado
Reembolsos vía credit memo	Sí
Tokenización	Sí
Picker de tarjetas guardadas	Sí (clientes con sesión; "Use a new card" cae al hospedado)
Suscripciones	No nativas en Magento CE (requiere Adobe Commerce o una extensión recurring de terceros)
i18n	Sí — CSVs en_US, fr_FR, es_ES, pt_BR

Reembolsos

Desde la página de orden admin → Credit Memo → Refund. Magento llama al refund() del módulo que hace POST a POST /api/v1/payments/{id}/refund. Una idempotency key ligada al payment entity id + monto previene doble reembolsos al re-enviar.

Seguridad de webhooks

El controller del webhook autentica vía HMAC-SHA256 (X-GC-Signature sobre {timestamp}.{body}, ventana de 5 minutos) y declara CsrfAwareActionInterface::validateForCsrf → true porque no necesita el token CSRF de Magento (la firma es el mecanismo de auth).

Solución de problemas

• Método ausente de la lista — confirma "Enabled" Yes y que el país de billing no esté bloqueado en Sales → Payment Methods → Genius Checkout → Allowed Countries.
• Lista de tarjetas guardadas vacía — verifica que el customer id de la tienda esté mapeado en GC (el proxy usa customer.entity_id); un comprador nuevo ve [] hasta su primer checkout.
• Logo no se renderiza — Model/ConfigProvider::logo_url cae a AssetRepository::getUrl('GeniusCheckout_Payment::images/genius-checkout-logo.svg'). Limpia caché de static-content: bin/magento cache:flush && bin/magento setup:static-content:deploy.
• No gateway configuration found for this merchant — verifica que tengas un gateway conectado en el panel GC para el modo activo (test vs live).