Odoo Plugin

The Genius Checkout payment provider for Odoo adds Genius Checkout as a native payment option in Odoo's Payment module. It supports hosted card checkout, partial and full refunds from the accounting screens, saved cards via tokenization, and Odoo Subscriptions through merchant-initiated transactions.

Requirements

• Odoo 17.0, 18.0, or 19.0 (Community or Enterprise). A 16.0 backport is straightforward — see "Odoo 16 backport" below.
• A Genius Checkout merchant account with the Odoo integration enabled under Merchant → Connected Apps.

Install

Step 1 — connect on the GC side first

Do this before installing the Odoo module so you have your webhook secret on hand:

1. Sign in to https://app.geniuscheckout.com.
2. Connected Apps → Connect Odoo.
3. Paste your Odoo URL + Odoo personal API key.
4. GC will display a one-time webhook secret — copy it now.

Step 2 — install the module in Odoo

1. Copy the module folder into your Odoo addons path as payment_geniuscheckout (or use odoo.sh's GitHub branch import).
2. Restart Odoo and update the apps list.
3. Apps → search "Genius Checkout" → Install.

Step 3 — configure the provider

Accounting → Configuration → Payment Providers → Genius Checkout:

Setting	Value
API Key	Your gc_test_… or gc_live_… key (the prefix controls which environment is used at checkout)
Webhook Secret	The value you copied from the GC dashboard in step 1
State	Test Mode (while validating) or Enabled (live)

Checkout flow

1. Customer reaches Odoo's checkout, picks Credit / Debit Card (the GC method).
2. The provider creates a checkout session via POST /api/v1/checkout-sessions and redirects the customer to GC's hosted checkout.
3. Customer completes payment (3DS handled by GC).
4. Asynchronously, GC pushes the event to /payment/geniuscheckout/webhook. The receiver verifies HMAC-SHA256 over {timestamp}.{body} and transitions the Odoo payment transaction.
5. The browser-side return path at /payment/geniuscheckout/return re-fetches the GC session by id and trusts only the API's status (return-URL tampering is rejected).

Supported features

Capability	Status
Refunds (full + partial)	Yes — Odoo 17 live-verified
Tokenization	Yes — customers can save a card at checkout
Saved cards	Yes — one-click reuse on subsequent orders
Subscriptions	Yes — works with Odoo Subscriptions; recurring invoices charge via /api/v1/payments with MIT semantics
HMAC webhook auth	Yes — {timestamp}.{body}, hex, per-instance secret
i18n	Yes — strings translated; help text aligned with PO files

Subscriptions

If the sale_subscription module is installed, GC automatically appears as a payment provider for subscription products. The first sale captures the card and tokenizes it; subsequent invoices are charged silently via _send_payment_request — no customer redirect required.

Refunds

From a confirmed sale order or invoice:

1. Open the related Payment Transaction.
2. Click Refund (Odoo's standard action — surfaced automatically once support_refund='partial' is detected on the provider).
3. Enter an amount (≤ original) or leave blank for a full refund.
4. Odoo creates a refund transaction; the module sends it to POST /api/v1/payments/{id}/refund and reflects the response state on the refund TX.

Endpoints

Route	Direction	Purpose
/payment/geniuscheckout/return	inbound (browser)	Customer returns from GC checkout
/payment/geniuscheckout/webhook	inbound (S2S)	Server-to-server transaction events

Webhook security

• HMAC-SHA256 over {timestamp}.{body} (hex) in the X-GC-Signature header.
• 5-minute replay window on X-GC-Timestamp.
• Webhook receiver rejects providers whose configured secret is empty or under 16 characters.

Odoo 16 backport

Replace the support_refund selection extension with support_refund_partial and adjust the _get_specific_rendering_values signature (Odoo 16 used a different processing-values shape). Everything else ports cleanly.

Troubleshooting

• Order stays in draft after payment — confirm the webhook URL on the GC dashboard matches your Odoo public hostname; check the Odoo log for HMAC verification failures.
• /return URL doesn't move the order forward — that's intentional: the browser-side return path now re-fetches the GC session and trusts only the API's status, so a tampered URL stays in draft. Wait for the webhook (usually within a few seconds).
• Generic provider icon showing — clear Odoo's static cache; the icon ships under static/description/icon.png and is wired in data/payment_provider_data.xml.

Support

• Module issues: github.com/geniuscheckout/odoo-module/issues
• GC support: [email protected]