> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepaykit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Comgate

> Comgate provider for PayKit.

```bash theme={null}
npm install @paykit-sdk/comgate
```

## Setup

<Tabs>
  <Tab title="Environment variables">
    ```typescript theme={null}
    import { PayKit } from '@paykit-sdk/core';
    import { comgate } from '@paykit-sdk/comgate';

    export const paykit = new PayKit(comgate());
    ```

    Required env vars:

    ```bash theme={null}
    COMGATE_MERCHANT=your-merchant-id
    COMGATE_SECRET=your-secret
    COMGATE_SANDBOX=true
    ```
  </Tab>

  <Tab title="Direct config">
    ```typescript theme={null}
    import { PayKit } from '@paykit-sdk/core';
    import { createComgate } from '@paykit-sdk/comgate';

    export const paykit = new PayKit(
      createComgate({
        merchant: 'your-merchant-id',
        secret: 'your-secret',
        isSandbox: true,
      }),
    );
    ```
  </Tab>
</Tabs>

## How it works

```typescript theme={null}
const checkout = 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',
});

// Redirect the customer to checkout.payment_url
```

Comgate doesn't support customers, subscriptions, or updating checkouts/payments. It also doesn't support retrieving checkouts — use `paykit.payments.retrieve` 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.

```typescript theme={null}
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 status | PayKit events emitted |
| - | - |
| `PAID` | `payment.succeeded` + `invoice.generated` |
| `PENDING` | `payment.created` |
| `AUTHORIZED` | `payment.updated` |
| `CANCELLED` | `payment.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:

```typescript theme={null}
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

```typescript theme={null}
// 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
  },
});
```

## Escape hatch

`paykit._native` returns PayKit's [HTTP client](/concepts/http-client), already pointed at Comgate and authenticated with your credentials. Use it to call endpoints PayKit does not map yet.

```typescript theme={null}
const result = await paykit._native.get('/v2.0/payment/pay_123.json');

if (result.ok) console.log(result.value);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.