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.

Comgate API docs | Medusa Payment Module

Features

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

Install

1
bun add medusa-plugin-comgate

Configure

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

1234567891011121314151617181920
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-plugin-comgate/providers/comgate",
            id: "comgate",
            options: {
              merchant: process.env.COMGATE_MERCHANT,
              secret: process.env.COMGATE_SECRET,
              test: process.env.COMGATE_TEST === "true",
              // optional:
              // preauth: false,
              // lang: "cs",
              // country: "CZ",
              // label: "My Store",
              // method: "ALL",

Options

Option Required Default Description Copy to clipboardmerchant yes — Comgate e-shop identifier. Copy to clipboardsecret yes — Password for background communication. Copy to clipboardtest no Copy to clipboardtrue Test mode. Copy to clipboardpreauth no Copy to clipboardfalse Create pre-authorizations; capture later. Copy to clipboardlang no Copy to clipboardcs Gateway / e-mail language (ISO 639-1). Copy to clipboardcountry no Copy to clipboardALL Payer country (ISO 3166-1). Copy to clipboardlabel no Copy to clipboardOrder Statement label, 1–16 chars. Copy to clipboardmethod no Copy to clipboardALL Payment method, or Copy to clipboardALL to let the payer choose. Copy to clipboardurl_paid / Copy to clipboardurl_cancelled / Copy to clipboardurl_pending no — Return URLs. See note below — bake your own order id into them. Copy to clipboardbase_url no Copy to clipboardhttps://payments.comgate.cz API base url (the Copy to clipboard/v2.0 version prefix is part of each path).

Pre-authorization

To run both a direct-capture and a pre-auth provider, register the module twice with different Copy to clipboardids and Copy to clipboardoptions.preauth:

1234
providers: [
  { resolve: "medusa-plugin-comgate/providers/comgate", id: "comgate", options: { /* preauth: false */ } },
  { resolve: "medusa-plugin-comgate/providers/comgate", id: "comgate-preauth", options: { preauth: true } },
]

The provider id used in the storefront / API is Copy to clipboardpp_comgate_comgate (and Copy to clipboardpp_comgate-preauth_comgate-preauth).

How it works

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

1. Copy to clipboardinitiatePayment → Copy to clipboardPOST /v2.0/payment.json. Returns Copy to clipboarddata.redirect — send the payer there. The Medusa payment session id is passed as Comgate Copy to clipboardrefId.
2. The payer pays on the Comgate gateway.
3. Webhook → Comgate POSTs a JSON background notification to Copy to clipboard/hooks/payment/comgate_comgate. Copy to clipboardgetWebhookActionAndData constant-time-verifies the echoed Copy to clipboardsecret, resolves the session by Copy to clipboardrefId, and maps Copy to clipboardPAID → captured, Copy to clipboardAUTHORIZED → authorized, Copy to clipboardCANCELLED → failed.
4. Copy to clipboardcapturePayment → no-op for direct capture (already Copy to clipboardPAID); Copy to clipboardPUT /v2.0/preauth/transId/{id}.json in pre-auth mode.
5. Copy to clipboardrefundPayment → Copy to clipboardPOST /v2.0/refund.json. Copy to clipboardcancelPayment → Copy to clipboardDELETE /v2.0/payment/transId/{id}.json (storno, PENDING only) or Copy to clipboardDELETE /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 Copy to clipboardsecret in the body (no HMAC header). Restrict the webhook to Comgate's IP ranges (Copy to clipboardhttps://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:

Field (CS) Field (EN) Value Heslo Password → your Copy to clipboardCOMGATE_SECRET Povolený způsob založení platby Payment creation method HTTP POST protokol - backend (recommended) Url pro předání výsledku platby Background result URL (PUSH) Copy to clipboardhttps://<your-backend>/hooks/payment/comgate_comgate Url zaplacený Paid redirect storefront order-confirmation page Url zrušený Cancelled redirect storefront cart / retry page Url nevyřízený Pending redirect storefront "payment processing" page Povolené IP adresy / Povolit všechny IP Allowed IPs your backend's egress IP, or allow-all

The PUSH URL is mandatory — without it payments never confirm in Medusa. 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 Copy to clipboard${id} (Comgate transId) and Copy to clipboard${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 Copy to clipboardurl_paid / Copy to clipboardurl_cancelled / Copy to clipboardurl_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):

123
Paid:      https://<storefront>/${countryCode}/order/confirmed?state=paid&id=${id}&refId=${refId}
Cancelled: https://<storefront>/${countryCode}/cart?state=cancelled&id=${id}&refId=${refId}
Pending:   https://<storefront>/${countryCode}/order/pending?state=pending&id=${id}&refId=${refId}

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

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

Copy to clipboardrefId 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:

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

Development

123
bun install
bun run build      # tsc -> dist
bun run test       # jest unit tests (mocked fetch)

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

1
COMGATE_MERCHANT=xxxx COMGATE_SECRET=xxxx bun run smoke

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

Publishing to npm / Medusa integrations page

This is packaged as a Medusa v2 plugin. To list it for free on the Medusa integrations page, the Copy to clipboardpackage.json already includes the required keywords (Copy to clipboardmedusa-v2, Copy to clipboardmedusa-plugin-integration, Copy to clipboardmedusa-plugin-payment).

12
bun run plugin:build   # medusa plugin:build -> .medusa/server
npm publish            # public package

Once published with those keywords, the plugin is picked up automatically by the Medusa integrations listing.

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.