This plugin is a Comgate payment provider for Medusa v2. Comgate is a Czech payment gateway. It accepts cards, Apple Pay, Google Pay, Czech and Slovak bank buttons, Twisto and other methods.
Disclaimer: This plugin is an unofficial integration from the community. Comgate Payments, a.s. does not own, approve or maintain it. "Comgate" and the Comgate logo are trademarks of their owner. This document uses them only to identify the payment gateway.
npm | Medusa integrations listing | Comgate API docs | Medusa Payment Module
- Checkout with a redirect to the Comgate gateway (background create with
prepareOnly). - Optional pre-authorization mode. The gateway reserves the amount now, and you capture it later.
- Capture, cancel and refund from the admin dashboard.
- The plugin receives PUSH notifications (the webhook) at the Medusa endpoint
/hooks/payment/comgate_*.
bun add medusa-plugin-comgateAdd the provider to the Payment Module in medusa-config.ts:
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,
// Fail safe: only an explicit "false"/"0" switches to production,
// so a typo or an unset var stays in the sandbox.
test: !["false", "0"].includes((process.env.COMGATE_TEST ?? "").toLowerCase()),
// optional:
// preauth: false,
// lang: "cs",
// country: "CZ",
// label: "My Store",
// method: "ALL",
},
},
],
},
},
],
})| Option | Required | Default | Description |
|---|---|---|---|
merchant |
yes | — | The e-shop identifier in Comgate. |
secret |
yes | — | The password for server-to-server calls. |
test |
no | true |
Test mode. |
preauth |
no | false |
Create pre-authorizations. You capture them later. |
lang |
no | cs |
The language of the gateway and the e-mails (ISO 639-1). |
country |
no | ALL |
The country of the payer (ISO 3166-1). |
label |
no | Order |
The label on the bank statement, 1–16 characters. |
method |
no | ALL |
The payment method. ALL lets the payer select the method. |
url_paid / url_cancelled / url_pending |
no | — | Return URLs. Put your own order ID in them. Refer to the note below. |
base_url |
no | https://payments.comgate.cz |
The API base URL. Each path includes the /v2.0 prefix. Comgate accepts only IPv4 addresses on its allow list and returns 1400 for other calls. If your host sends requests over IPv6, set this to an IPv4 relay. |
proxy_key |
no | — | The shared secret of the relay in base_url. The plugin sends it as the X-Proxy-Key header on each API call. Do not set it if you call Comgate directly. |
Retries and credentials:
- Each try stops after 15 s.
- If a network error occurs and no HTTP response comes back, the plugin tries the call again. It makes up to 4 tries and waits 1 s, 2 s and 3 s between them. Thus a relay that starts after an auto-suspend does not cause a failure.
- Refunds and pre-auth captures try again only if the connection did not open (refused, DNS error, connect timeout). If the connection stops during a request, the money can already be moved. In that case, the plugin returns the error.
- The plugin does not try a request again if an HTTP response came back.
- The plugin removes the credentials (
secret, the Basic token,proxy_key) from all errors and log messages.
You can use a direct-capture provider and a pre-auth provider together. To do this, register the module two times with a different id and options.preauth:
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 storefront and the API use the provider ID pp_comgate_comgate. The pre-auth provider ID is pp_comgate-preauth_comgate-preauth.
The plugin uses the Comgate REST v2.0 JSON API (https://payments.comgate.cz/v2.0/...) with HTTP Basic authentication.
-
initiatePayment→POST /v2.0/payment.json. The response hasdata.redirect. Send the payer to this URL. The plugin sends the ID of the Medusa payment session as the ComgaterefId. -
The payer pays on the Comgate gateway.
-
Webhook → Comgate sends a PUSH notification (JSON or form-encoded) to
/hooks/payment/comgate_comgate.getWebhookActionAndDatadoes these checks:- If the PUSH notification has a
secret, thesecretmust be correct. The plugin compares it in constant time. - The plugin gets the canonical status, price, currency and
refIdfromGET /v2.0/payment/transId/{id}.json. It does not use these values from the PUSH body. If this API is not available, the plugin uses the PUSH body only if itssecretis correct. In all other conditions, it does nothing. - The Comgate
refIdmust be equal to the PUSHrefId(the ID of the Medusa payment session). ThetransIdstored on the payment session must be empty or equal to the PUSHtransId. - The canonical price and currency must be equal to the amount and currency of the payment session (anti-tamper check).
- The plugin maps
PAID → captured,AUTHORIZED → authorized,CANCELLED → failedandPENDING → pending. It convertsamountfrom Comgate minor units to the Medusa decimal value.
If a check fails, the plugin returns
not_supportedand logs an error. The payment does not change. Medusa ignoresfailed, so a lateCANCELLEDafterPAIDchanges nothing. A secondPAIDdoes not capture again. - If the PUSH notification has a
-
capturePayment→ For direct capture, this step does nothing because the payment is alreadyPAID. In pre-auth mode, the plugin callsPUT /v2.0/preauth/transId/{id}.json. -
updatePayment→ Comgate cannot change the amount of a payment. If the amount or currency changes, the plugin cancels the old Comgate payment. Then it creates a new payment with the samerefId. -
refundPayment→POST /v2.0/refund.json. The plugin sends thetestflag of the original payment. If the flags are different, Comgate returns error 1402.cancelPayment→DELETE /v2.0/payment/transId/{id}.json(storno, only for PENDING). In pre-auth mode, the plugin callsDELETE /v2.0/preauth/transId/{id}.json.
The Comgate specification requires that the PUSH notification controls order fulfillment. The browser redirect of the payer must not control it, because the payer can change the redirect parameters. Comgate sends the PUSH notification again, up to 1000 times, until it gets a 2xx response. The webhook in Medusa is idempotent.
Comgate authenticates the PUSH notification with the merchant
secretin the body. It does not send an HMAC header. As the first layer of protection, accept webhook calls only from the Comgate IP ranges (https://payments.comgate.cz/ips-v4). Thesecretcheck is the second layer.
Go to the Client Portal → Integrace → Nastavení obchodů → Přidat propojení obchodu. Set these fields:
| Field (CS) | Field (EN) | Value |
|---|---|---|
| Heslo | Password | → your COMGATE_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) | https://<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 |
You must set the PUSH URL. Without it, Medusa never gets the payment confirmation.
When you save the connection, the portal sends a GET request to the PUSH URL. The Medusa webhook route accepts only POST. Thus the plugin returns 200 for GET on that path, and the portal check passes.
The three redirect URLs are only for the browser. They are not authoritative, because the payer can change their parameters. Do not mark an order as paid from a redirect. Only the PUSH notification changes the order state.
The return page must identify the order. Comgate supports the placeholders ${id} (the Comgate transId) and ${refId} (your reference). The placeholders are case-sensitive. Comgate replaces them only in the return-URL fields of the Comgate client portal, at the time of the redirect.
Comgate uses the API fields url_paid, url_cancelled and url_pending verbatim. It does not replace placeholders and does not add parameters. If you set the URLs through the API, you must put the identifier in the URL yourself.
Portal (recommended, Comgate replaces the placeholders):
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, put in your own ID):
url_paid: https://<storefront>/${countryCode}/order/confirmed?refId=<order-id>
refId is the ID of the Medusa payment session. The return page reads it and finds the order. The redirect is never authoritative. Before the storefront shows "paid", it must get the order or payment status again on the server.
Do not select the Web/Mobile Checkout SDK checkboxes. This provider uses the hosted redirect flow of Comgate. It does not use the embedded checkout SDKs.
In the Comgate portal, set the PUSH notification URL ("Url pro předání výsledku platby") to:
https://<your-backend>/hooks/payment/comgate_comgate
bun install # also installs the git hooks (lefthook)
bun run build # medusa plugin:build -> .medusa/server
bun run test # jest unit tests (mocked fetch)
bun run check # format + lint + typecheck + test (what CI runs)The format and lint tools are from oxc. bun run format changes the files. bun run lint only checks them.
lefthook runs the format and lint checks on staged files before each commit. It runs the typecheck and the tests before each push. The hooks only check files. They do not change files during a commit.
If the format check fails:
- Run
bun run format. - Stage the files again.
To do a live smoke test against the Comgate v2.0 test API, run this command. You do not need a Medusa backend.
COMGATE_MERCHANT=xxxx COMGATE_SECRET=xxxx bun run smokeThe command creates a test payment and shows the redirect URL.
- Open the
redirectURL. - Pay with a Comgate test card.
- Make sure that the status changes to
PAID.
The shop connection must allow your IP address (portal → Povolené IP adresy / Povolit všechny IP).
MIT
This project is an independent, unofficial integration. Comgate Payments, a.s. does not own or approve it. All Comgate trademarks and logos are the property of their owner.
