Magento 2 Plugin

The Genius Checkout module for Magento 2 adds Genius Checkout as a payment method, with admin configuration, a Knockout frontend renderer in checkout, a saved-card picker for signed-in customers, and refund handling via Magento's standard credit-memo flow.

Install

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

Configure

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

Setting	Value
Enabled	Yes
API Key	Your gc_test_… or gc_live_… key (admin field, encrypted at rest)
Webhook Secret	Same value as GC Dashboard → Developers → Webhooks
Test Mode	Yes until you go live
New Order Status	Status to apply after payment authorization
Sort Order	Position in the checkout payment list

Then in the GC dashboard, set your Magento store's webhook URL to:

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

Subscribe the endpoint to at least: payment.completed, payment.failed, payment.refunded, payment.voided.

Checkout flow

1. Shopper reaches Magento's checkout, picks Genius Checkout in the payment-method list (rendered by the Knockout component).
2. On place-order, the place-order mixin redirects the shopper to the GC hosted checkout URL.
3. Shopper completes payment; GC POSTs payment.completed to the webhook receiver, which moves the Magento order into the configured status.

Saved cards (signed-in shoppers)

For signed-in customers, the renderer shows a radio list of previously-saved cards, sourced via the server-side /geniuscheckout/index/savedcards proxy:

• The proxy forwards the call to GET /api/v1/customers/{external_customer_id}/payment-tokens under the merchant's API key — the API key never reaches the browser.
• The proxy uses Authorization: Bearer ….
• Only {id, brand, last4, expiry_month, expiry_year} is surfaced to the page.
• Selecting a saved card sets additional_data.payment_token_id on the place-order payload so the backend charges the vaulted token directly instead of the hosted-redirect flow. Selecting "Use a new card" falls back to the hosted-redirect.

Supported features

Capability	Status
Refunds via credit memo	Yes
Tokenization	Yes
Saved-card picker	Yes (signed-in shoppers; "Use a new card" falls back to hosted-redirect)
Subscriptions	Not natively in Magento CE (needs Adobe Commerce or a third-party recurring extension)
i18n	Yes — en_US, fr_FR, es_ES, pt_BR CSVs

Refunds

From the admin order page → Credit Memo → Refund. Magento calls the module's refund() which POSTs to POST /api/v1/payments/{id}/refund with the credit-memo amount. An idempotency key tied to the Magento payment entity id + amount prevents double-refunds on re-submit.

Webhook security

The webhook controller authenticates via HMAC-SHA256 (X-GC-Signature over {timestamp}.{body}, 5-minute replay window) and declares CsrfAwareActionInterface::validateForCsrf → true because it doesn't need Magento's CSRF token (signature is the auth mechanism).

Troubleshooting

• Method missing from checkout list — confirm "Enabled" is Yes and that the customer's billing country isn't blocked under Sales → Payment Methods → Genius Checkout → Allowed Countries.
• Saved-card list empty for signed-in shopper — verify the storefront customer id is mapped on the GC side (the proxy uses customer.entity_id); a new shopper sees [] until their first checkout.
• Logo not rendering — Model/ConfigProvider::logo_url falls back to AssetRepository::getUrl('GeniusCheckout_Payment::images/genius-checkout-logo.svg'). Clear static-content cache: bin/magento cache:flush && bin/magento setup:static-content:deploy.
• No gateway configuration found for this merchant — make sure a payment gateway is connected in your GC dashboard for the active mode (test vs live).