Skip to main content
npm install @paykit-sdk/comgate

​
Setup

import { PayKit } from '@paykit-sdk/core';
import { comgate } from '@paykit-sdk/comgate';

export const paykit = new PayKit(comgate());
Required env vars:
COMGATE_MERCHANT=your-merchant-id
COMGATE_SECRET=your-secret
COMGATE_SANDBOX=true

​
How it works

Comgate authenticates via HTTP Basic (merchant ID + secret, base64-encoded). createCheckout calls POST /v2.0/paymentRedirect/merchant/{merchant} and redirects the user to Comgate’s hosted payment page — the returned checkout object is null because the redirect is handled automatically. After payment, Comgate posts a webhook with the transaction status. createPayment (non-hosted) calls POST /v2.0/payment and requires the customer to be identified by id. Currency defaults to CZK if not set.
Comgate does not support customers, subscriptions, or updating checkouts/payments. It also does not support retrieving checkouts — use retrievePayment to look up transaction status instead.

​
Webhooks

Comgate sends a POST with merchant, secret, transId, and status fields in the body. PayKit verifies the secret and merchant ID directly, then calls /v1.0/status to confirm the transaction status server-side. 
const webhook = paykit.webhooks
  .setup({ webhookSecret: process.env.COMGATE_SECRET! })
  .on('payment.created', async event => {
    /* PENDING transaction */
  })
  .on('payment.updated', async event => {
    /* AUTHORIZED (pre-auth, awaiting capture) */
  })
  .on('payment.succeeded', async event => {
    /* PAID transaction */
  })
  .on('payment.failed', async event => {
    /* CANCELLED transaction */
  })
  .on('invoice.generated', async event => {
    /* emitted alongside payment.succeeded on PAID */
  });

await webhook.handle({
  body: rawBody,
  headersAsObject: Object.fromEntries(request.headers),
  fullUrl: request.url,
});
Comgate statuses and their PayKit event mappings:
Comgate statusPayKit events emitted
PAIDpayment.succeeded + invoice.generated
PENDINGpayment.created
AUTHORIZEDpayment.updated
CANCELLEDpayment.failed

​
Raw Comgate events

Comgate webhooks carry a status field rather than named event types. You can listen for the raw status values via the comgate.* namespace: 
paykit.webhooks
  .setup({ webhookSecret: process.env.COMGATE_SECRET! })
  .on('comgate.PAID', async event => {
    // event.data is the verified Comgate status response
  })
  .on('comgate.CANCELLED', async event => {
    /* ... */
  });

​
provider_metadata

// checkout.provider_metadata — label is optional (defaults to "Order from Eshop")
await paykit.checkouts.create({
  customer: { email: 'user@example.com' },
  item_id: 'my-product',
  session_type: 'one_time',
  quantity: 1,
  amount: 2900,
  currency: 'CZK',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  provider_metadata: {
    label: 'Order #1234',
  },
});

// payment.provider_metadata — email is required; paymentLabel is optional
await paykit.payments.create({
  customer: { id: 'payer-42' },
  item_id: 'my-product',
  amount: 2900,
  currency: 'CZK',
  provider_metadata: {
    email: 'user@example.com',        // required
    paymentLabel: 'Order from Eshop', // optional
  },
});