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

# Setup CoinGate

> Connect your own CoinGate account to accept crypto on Komerza

Accept crypto through your own **CoinGate** account. Buyers choose crypto at checkout and pay on CoinGate's hosted payment page, in any coin CoinGate supports. Payments land in your CoinGate balance, and CoinGate charges a **1%** processing fee on its [Standard plan](https://coingate.com/pricing).

Komerza only needs one thing from CoinGate: an **API token**. Each payment tells CoinGate where to send its updates, so there's no callback URL for you to set up.

> [!NOTE]
>
> CoinGate works differently from NOWPayments and Heleket. Buyers pick their
> coin on CoinGate's page rather than in Komerza, so CoinGate takes every coin
> it supports at once and isn't part of **Coin Routing**.

## Prerequisites

* A **verified CoinGate business account**. On [coingate.com](https://coingate.com/), create a business account from your personal dashboard and complete business verification - CoinGate won't let you receive payments until it's approved. Your store has to be live and publicly reachable before CoinGate approves it.
* A **live** account. Tokens from CoinGate's sandbox at [sandbox.coingate.com](https://sandbox.coingate.com/) can't take real payments, and Komerza won't accept them.

**1. Create an API key in CoinGate**

1. Log into your [CoinGate dashboard](https://account.coingate.com/). In the sidebar, click **Integrations**, then **API management**.

   ![CoinGate Integrations page with the API management, Plugins and Payment buttons cards](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/integrations.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=dd7f444d18e3d6245327c91756514207)

2. Click **New API key**.

   ![CoinGate API management page on the Integrations tab, with the New API key button and one existing key](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/api-management.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=f8d36527fe67a2d0c00b258cc789a495)

3. Enter an **API key title** you'll recognise, such as `Komerza`. To accept payments that arrive slightly short, also set **Underpaid cover percentage** - see [Underpayments](#underpayments).

   ![Configure your API key section with Komerza as the API key title and the Underpaid cover percentage field set to 0](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/api-key-title.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=67fb2d948f42beaa343d25006c8f3280)

4. Under **Advanced options**, leave **Whitelisted IP addresses** empty. A key with addresses listed only answers requests from those addresses, so it would refuse Komerza and every payment would fail. **Callback format** can stay as it is - Komerza reads both. Turn on **Paid notifications** if you want CoinGate to notify you about each payment.

   ![Advanced options with an empty Whitelisted IP addresses field, Paid notifications off, Callback format set to Form encoding, and the Create authorization token button](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/api-key-advanced.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=b0b268074e5cdb33464ce2e28782bd6a)

5. Click **Create authorization token** and copy the token.

> [!WARNING]
>
> CoinGate shows the token **only once**. Paste it into Komerza straight
> away or keep it somewhere safe. If you lose it, create a new API key and
> use its token instead.

CoinGate recommends a separate API key for each website or service, so create one just for Komerza rather than reusing a key from another integration.

**2. Connect CoinGate in Komerza**

1. In your dashboard, click **Settings** at the bottom of the sidebar, then **Cryptocurrency**. If it isn't listed yet, click **Payment Methods**, then **Set up** on the **Cryptocurrency** card under **Available Payment Methods**.

2. Under **Processors**, find **CoinGate** and click **Connect**.

   ![CoinGate under Processors on the Cryptocurrency page, marked Not connected, with its Connect button](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/processor-light.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=97a0abeca2530b52c8ca1c5ae705e26e)

3. Paste the token into **API token**.

4. Under **Get paid in**, choose what CoinGate credits you in - see [Choosing what you get paid in](#choosing-what-you-get-paid-in). Keeping the crypto is the default.

5. Click **Save changes**.

![Configure CoinGate dialog with the API token field, the Get paid in dropdown set to Keep the crypto buyers pay with, and the How buyers pay notice](https://mintcdn.com/komerza/tDzwje8AduDaNtri/images/coingate/connect-light.png?fit=max\&auto=format\&n=tDzwje8AduDaNtri\&q=85\&s=e51ce6cdcc9c99a2f14b17d08226d705)

Komerza checks the token with CoinGate before saving, so a mistyped, deleted or sandbox token is caught here instead of at checkout. Once it's saved, the card shows **Connected**.

> [!TIP]
>
> CoinGate lives on the **Cryptocurrency** page, not **Payment Methods**. If
> it's your only crypto option, **Payment Methods** lists it as
> **Cryptocurrency** "Through CoinGate", and **Configure** brings you back
> here.

**3. Test with a small payment**

A live CoinGate account has no test mode, so make a small real purchase on your store. Pay with crypto, and check the order is delivered once CoinGate confirms the payment.

## Choosing what you get paid in

**Get paid in** decides what CoinGate credits to your balance for each payment.

| Option | What happens |
| - | - |
| **Keep the crypto buyers pay with** (default) | No conversion. You're credited in each coin as it's paid. |
| A fiat currency, e.g. **Euro (EUR)**, **British Pound (GBP)** or **United States Dollar (USD)** | CoinGate converts every payment and credits you in that currency. |
| A coin, e.g. **Bitcoin (BTC)** or **USDC (USDC)** | CoinGate converts every payment to that coin. |

The list comes live from CoinGate, so it always matches what CoinGate currently settles in. Your choice applies to every Komerza payment and replaces the settlement currency set in your CoinGate dashboard. CoinGate's 1% exchange fee only applies to conversions you make by hand, not to automatic conversions at checkout.

To change it later, click **Manage** on the CoinGate card, pick a new option and click **Save changes**. Leave **API token** empty to keep the token you already saved.

## What your customers see

1. At checkout, the buyer chooses **Cryptocurrency**. If CoinGate is your only crypto option, they go straight to it. If you also accept coins through self-custody, NOWPayments or Heleket, CoinGate appears in the coin list as **Other coins**.
2. Komerza sends them to CoinGate's payment page, where they pick a coin and pay.
3. Once they've picked a coin, the order shows as **Verifying** in your dashboard. It stays there while the network confirms the payment, and your unpaid-order window doesn't cancel it.
4. When CoinGate marks the payment **Paid**, Komerza delivers the order.

If the buyer leaves without paying, or CoinGate's payment page expires, the order goes back to waiting for payment and they can try again.

Komerza checks every payment with CoinGate directly: when CoinGate sends an update, while the buyer waits on the checkout page, and again every 15 minutes in case an update goes missing.

## Underpayments

Wallets and exchanges often take their own fee before sending, so a buyer can send slightly less than the amount due. With **Underpaid cover percentage** at 0, CoinGate doesn't mark a short payment as paid, so the order isn't delivered.

To accept small shortfalls, set **Underpaid cover percentage** on your API key, up to 10%. A payment within that margin is marked paid, Komerza delivers the order, and you absorb the difference. CoinGate suggests between 1% and 3%, and still charges its fee on the full order amount.

To change it on an existing key, go to **Integrations → API management** in CoinGate, open the key, update the percentage and save.

## Refunds

Komerza can't send crypto back through CoinGate, because CoinGate needs the buyer's wallet address, which only CoinGate collects. Choose **one** of these:

* **Return the crypto in CoinGate.** Go to **Sales → Orders**, open the paid order and click **Submit refund**. Enter the amount, the refund currency, the buyer's email and their wallet address. CoinGate can ask the buyer to confirm by email before it sends anything. Refunds come out of your CoinGate balance, and CoinGate charges a small refund fee. The order stays **Delivered** in Komerza.
* **Give store credit in Komerza.** Click **Process refund** on the order page. For CoinGate orders, the refund always goes to the customer's store balance as credit.

> [!WARNING]
>
> Never do both. **Process refund** on a CoinGate order always credits the
> customer's store balance, so refunding in CoinGate as well pays them twice.

## Changing or disconnecting

* **Use a new token:** click **Manage** on the CoinGate card, paste the new token and click **Save changes**. A token from a different CoinGate account is refused while payments on the current one are still confirming - link it once they've finished.
* **Disconnect:** click **Disconnect** on the CoinGate card. CoinGate comes off your checkout straight away and Komerza forgets your token. Payments that are already confirming still finish and are delivered.

Don't delete the API key in CoinGate while payments are still confirming. Komerza uses it to check those payments, so they couldn't be delivered.

## Troubleshooting

| Problem | Fix |
| - | - |
| "That is a CoinGate sandbox token" | The key was made on sandbox.coingate.com. Create one in your live account at coingate.com. |
| "CoinGate did not accept this token" | Copy the whole token again. If it was lost or the key was deleted, create a new API key. |
| "This token belongs to a different CoinGate account" | Payments on the account you're linked to are still confirming. Link the new account once they've finished. |
| "We could not reach CoinGate" | CoinGate didn't respond. Try again in a minute. |
| **Get paid in** only offers Keep the crypto buyers pay with | Komerza couldn't load CoinGate's settlement currencies. Close the dialog and try again later. |
| Buyers see "Paying with crypto is not available for this store right now" | CoinGate refused to create the payment. Check your business verification is approved, the API key still exists, and **Whitelisted IP addresses** on the key is empty. |
| An order stays on **Verifying** | The buyer has picked a coin and the network is still confirming. It's delivered automatically once CoinGate marks it paid. In CoinGate, **API management → Callbacks** shows progress. |
| A buyer paid slightly less and the order wasn't delivered | The payment fell outside your **Underpaid cover percentage**. Raise it on your API key so small shortfalls are accepted in future. |


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