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

# FreeKassa setup

> Accept cards, SBP, wallets and crypto with FreeKassa, paid into your own FreeKassa account.

FreeKassa lets buyers pay by bank card, SBP, MIR, wallets and crypto. Payments go to **your own** FreeKassa account. Join Markt never holds the money.

The buyer pays on the FreeKassa page. The order completes when FreeKassa sends a signed payment notification to your store.

> [!NOTE]
>
> FreeKassa charges in **RUB, USD, EUR, UAH or KZT**. Your store currency must be one of these, or checkout shows an error for FreeKassa.

## What you need

| Field | Where to find it | Required |
| - | - | - |
| Shop ID | FreeKassa → Settings | Yes |
| Secret word 1 | FreeKassa → Settings (signs the payment link) | Yes |
| Secret word 2 | FreeKassa → Settings (signs the payment notification) | Yes |
| API key | FreeKassa → Settings → API | Optional |

The API key is only used to check a payment's status if the notification is late.

## Set up

**1. Open your FreeKassa settings**

Sign in at [merchant.freekassa.net](https://merchant.freekassa.net/settings) and open **Settings** for your shop. Copy the **Shop ID**.

**2. Set both secret words**

Choose **Secret word 1** and **Secret word 2**. Use two different long random values.

**3. Paste the notification URL**

In Join Markt, open **Configure → Payment methods → FreeKassa**. Copy the **Webhook URL** shown there, ending in `/api/freekassa/webhook`.

In FreeKassa, paste it as the **Notification URL** and choose **POST** as the notification method.

**4. Set the return URLs**

Join Markt shows two more links under the webhook URL. Paste them in FreeKassa:

| FreeKassa field | Value |
| - | - |
| Success URL | `https://<your store>/api/freekassa/return?status=success` |
| Failure URL | `https://<your store>/api/freekassa/return?status=fail` |

They send the buyer back to their order page, where they get what they bought. They never mark an order paid: only the signed notification does.

**5. Turn on payment confirmation**

Ask FreeKassa support to enable **payment confirmation**. FreeKassa then resends the notification until your store answers `YES`, so no payment is lost.

**6. Save in Join Markt**

Paste the Shop ID and both secret words, turn on **Active at checkout**, and save.

## How payments are checked

Every notification must pass all of these checks before the order is marked paid:

| Check | What happens if it fails |
| - | - |
| Sent from a FreeKassa server IP | Refused (403) |
| Signature matches Secret word 2 | Refused (401) |
| Shop ID matches your store | Refused |
| Amount is at least the order total | Refused |
| Order belongs to your store | Refused |

A repeated notification for an already paid order is answered `YES` and changes nothing.

## Test it

Turn on **test mode** in FreeKassa settings. FreeKassa then offers a test payment method that moves no real money.

## Troubleshooting

> [accordion] The order stays pending after payment
>
> * Check the Notification URL is exactly the one from Join Markt, with method **POST**.
> * Check Secret word 2 in Join Markt matches FreeKassa.
> * Add the API key so the store can check the status itself.

> [accordion] FreeKassa is missing at checkout
>
> Your store currency is not RUB, USD, EUR, UAH or KZT, or the method is not active.

> [accordion] Wrong signature on the FreeKassa page
>
> Secret word 1 in Join Markt does not match FreeKassa. Paste it again and save.


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