Comgate

medusa-plugin-comgate

Comgate payment provider for Medusa v2. Comgate is a Czech payment gateway (cards, Apple Pay / Google Pay, Czech & Slovak bank buttons, Twisto, etc).

Disclaimer: This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or maintained by Comgate Payments, a.s. "Comgate" and the Comgate logo are trademarks of their respective owner, used here only to identify the payment gateway this plugin integrates with.

npm | Medusa integrations listing | Comgate API docs | Medusa Payment Module

Features

• Redirect (background / prepareOnly) checkout flow.
• Optional pre-authorization mode (reserve now, capture later).
• Capture, cancel, refund from the admin dashboard.
• Background notification (webhook) handling via Medusa's /hooks/payment/comgate_* endpoint.

Install

Configure

Add the provider to the Payment Module in medusa-config.ts:

Options

Each attempt times out after 15 s. Network errors (no HTTP response) are retried up to 4 attempts with 1 s / 2 s / 3 s backoff, so a relay waking from auto-suspend does not fail the call. Refunds and pre-auth captures retry only when the connection was never established (refused, DNS, connect timeout) — a drop mid-request may already have moved money, so it is surfaced instead. A request that got any HTTP response is never retried. Credentials (secret, the Basic token, proxy_key) are redacted from every thrown or logged message.

Pre-authorization

To run both a direct-capture and a pre-auth provider, register the module twice with different ids and options.preauth:

The provider id used in the storefront / API is pp_comgate_comgate (and pp_comgate-preauth_comgate-preauth).

How it works

Uses the Comgate REST v2.0 JSON API (https://payments.comgate.cz/v2.0/..., HTTP Basic auth).

1. initiatePayment → POST /v2.0/payment.json. Returns data.redirect — send the payer there. The Medusa payment session id is passed as Comgate refId.
2. The payer pays on the Comgate gateway.
3. Webhook → Comgate POSTs a background notification (JSON or form-encoded) to /hooks/payment/comgate_comgate. getWebhookActionAndData:
   • rejects a present-but-wrong secret (constant-time compare);
   • takes the canonical status, price, currency and refId from GET /v2.0/payment/transId/{id}.json, not from the PUSH body. If that API is unreachable it falls back to the PUSH body only when its secret verified; otherwise it does nothing;
   • requires Comgate's refId to equal the PUSH refId (the Medusa payment session id), and the session's stored transId to be absent or equal to the PUSH transId;
   • requires the canonical price and currency to equal the session's amount and currency (anti-tamper);
   • maps PAID → captured, AUTHORIZED → authorized, CANCELLED → failed, PENDING → pending, with amount converted from Comgate minor units to Medusa's decimal. Any failed check returns not_supported (no state change) and logs an error. Medusa ignores failed, so a late CANCELLED after PAID changes nothing, and a repeated PAID is a no-op capture.
4. capturePayment → no-op for direct capture (already PAID); PUT /v2.0/preauth/transId/{id}.json in pre-auth mode.
5. updatePayment → if the amount or currency changes, the plugin cancels the old Comgate payment and creates a new payment with the same refId. Comgate cannot change the amount of a payment.
6. refundPayment → POST /v2.0/refund.json, sending the test flag the payment was created with (a mismatch is Comgate error 1402). cancelPayment → DELETE /v2.0/payment/transId/{id}.json (storno, PENDING only) or DELETE /v2.0/preauth/transId/{id}.json in pre-auth mode.

Per Comgate's spec, order fulfillment must be driven by the background notification, not the payer's browser redirect, since redirect params are user-controlled. Comgate retries the PUSH up to 1000× until it gets a 2xx — Medusa's webhook handling is idempotent.

Comgate authenticates the PUSH by echoing the merchant secret in the body (no HMAC header). Restrict the webhook to Comgate's IP ranges (https://payments.comgate.cz/ips-v4) as a first layer; the secret check is the second.

Comgate Client Portal setup

In the Client Portal → Integrace → Nastavení obchodů → Přidat propojení obchodu:

The PUSH URL is mandatory — without it payments never confirm in Medusa. When you save the connection, the portal probes the PUSH URL with a GET; the plugin answers 200 on that path (Medusa's own webhook route is POST-only), so the check passes. The three redirect URLs are browser-facing only and non-authoritative (the payer can forge their params); never mark an order paid from them. Order state is driven solely by the PUSH webhook.

Storefront redirect URLs (Medusa Next.js starter)

The return page must know which order it is. Comgate supports ${id} (Comgate transId) and ${refId} (your reference) placeholders, case-sensitive — but only in the Comgate client-portal return-URL fields, where Comgate substitutes them at redirect time. The API url_paid / url_cancelled / url_pending request fields are used verbatim (no substitution, no params appended), so if you set the URLs via the API you must bake the identifier in yourself.

Portal (recommended — Comgate substitutes the placeholders):

API options (verbatim — bake in your own id):

url_paid: https://<storefront>/${countryCode}/order/confirmed?refId=<order-id>

refId is the Medusa payment session id. The return page reads it and looks the order up. The redirect is non-authoritative regardless — the storefront must re-query order/payment status server-side before showing "paid".

Web/Mobile Checkout SDK checkboxes: leave off. This provider uses Comgate's hosted redirect flow, not the embedded checkout SDKs.

Configure the webhook

In the Comgate portal set the background-notification URL ("Url pro předání výsledku platby") to:

https://<your-backend>/hooks/payment/comgate_comgate

Development

Formatting and linting use oxc: bun run format writes, bun run lint checks. lefthook runs format/lint checks on staged files pre-commit and typecheck/test pre-push — the hooks only check, they never rewrite files mid-commit. If the format check fails, run bun run format and re-stage.

Live smoke test against the Comgate v2.0 test API (no Medusa backend needed):

It creates a test payment and prints the redirect URL — open it and pay with a Comgate test card to see the status flip to PAID. Your IP must be allowed on the shop link (portal → Povolené IP adresy / Povolit všechny IP).

License

MIT

This project is an independent, unofficial integration and is not affiliated with or endorsed by Comgate Payments, a.s. All Comgate trademarks and logos are the property of their respective owner.