Интеграция FreedomPay в Казахстане: полный гайд для...

FreedomPay за пять лет стал вторым по доле рынка онлайн-эквайринга в Казахстане после Kaspi, обрабатывая миллиарды тенге транзакций ежемесячно. Для многих интернет-магазинов и сервисов он стал балансом между комиссиями и качеством API. Но чтобы реально получить выгоду от FreedomPay, интеграцию нужно сделать правильно с первого раза.

Этот материал — практический технический гайд по интеграции платёжного шлюза FreedomPay (Freedom Finance) для бизнеса в Казахстане на 2026 год. Разберем процесс подключения мерчанта, аутентификацию по API-ключу, создание платежей, обработку 3DS и вебхуков. Покажем реальные примеры HTTP-запросов, типичные ошибки и чек-лист выхода в прод. Гайд будет полезен backend-разработчикам, финтех-командам и e-commerce менеджерам, которые хотят снизить стоимость эквайринга и повысить конверсию платежей.

Бизнес-контекст FreedomPay и предпосылки интеграции

К 2026 году рынок безналичных платежей в Казахстане стабильно растет на 20–25% в год. По данным Freedom Holding Corp и открытой статистики Национального банка РК, доля онлайн-платежей в e-commerce продолжает увеличиваться, а средний чек в интернет-торговле держится в диапазоне 8 000–15 000 тенге. На этом фоне FreedomPay, платёжный шлюз от экосистемы Freedom Finance, занял устойчивое второе место на рынке онлайн-эквайринга после Kaspi по количеству активных интернет-мерчантов и объему обрабатываемых операций.

Для бизнеса это означает: если вы уже принимаете оплату через Kaspi Pay или Halyk Bank, добавление FreedomPay как альтернативного или основного провайдера может дать более выгодные комиссии и гибкость в настройке платежных сценариев. По отзывам крупных интернет-магазинов и SaaS-сервисов, комиссии FreedomPay для среднего бизнеса обычно находятся в диапазоне 1,7–2,2% за транзакцию в зависимости от оборота и категории торговца, что конкурентоспособно по сравнению с другими игроками.

Чтобы начать интеграцию, нужны несколько бизнес- и технических предпосылок.

Бизнес-предпосылки:

• Юридическое лицо или ИП, зарегистрированное в Казахстане.

• Банковский счет в тенге (KZT) в Freedom Bank или другом банке-партнере.

• KYC/AML проверка у FreedomPay: предоставление учредительных документов, сведений о бенефициарах, описания бизнеса и домена.

Техничекие предпосылки:

• Backend на любом языке (Node.js, Java, .NET, PHP, Go) с возможностью выполнять исходящие HTTPS-запросы и принимать входящие вебхуки.

• Домен с валидным SSL-сертификатом (TLS 1.2+), так как FreedomPay не отправляет уведомления на HTTP.

• Возможность хранить секретные ключи в защищенном виде (Vault, KMS, по крайней мере отдельное зашифрованное хранилище).

Регистрация мерчанта в FreedomPay обычно занимает от 2 до 10 рабочих дней. Процесс выглядит так:

1. Оставляете заявку на сайте Freedom Finance: форма «Интернет-эквайринг FreedomPay» с указанием юридического лица, оборотов и домена.

2. Менеджер запрашивает пакет документов (устав, свидетельство о регистрации, договор банковского счета, описание бизнес-модели).

3. После скоринга подписывается договор эквайринга и вам создат мерчант-аккаунт в системе FreedomPay.

4. В личном кабинете генерируется API-ключ, тестовая и боевая среда, а также настраиваются callback (notify_url) и домены для 3DS/hosted-страниц.

В этой статье мы будем опираться на типовую конфигурацию FreedomPay на казахстанском рынке: валюта по умолчанию KZT, поддержка 3DS 2.0 для Visa/Mastercard, комиссия в среднем 1,8–2,1% и выплаты один раз в день на расчетный счет. Такие компании как Alashed IT (it.alashed.kz) регулярно внедряют FreedomPay для интернет-магазинов, маркетплейсов, EdTech и подписочных сервисов, поэтому ниже приведены отработанные на практике подходы и примеры.

Регистрация мерчанта FreedomPay и API-аутентификация

После подписания договора с FreedomPay вам предоставляют доступ в личный кабинет мерчанта. Там в раздел «Интеграция» или «API» вы можете получить тестовый и боевой API-ключи. На 2026 год FreedomPay в Казахстане использует простую схему аутентификации по API-ключу в HTTP-заголовке без OAuth: ключ передается в заголовке X-API-Key для всех запросов к REST API.

Тестовая среда обычно имеет вид:

• API base URL (sandbox): https://sandbox.freedompay.kz/api/v1

• Hosted payment page: https://sandbox.freedompay.kz/pay

Боевая среда:

• API base URL (prod): https://api.freedompay.kz/v1

• Hosted payment page: https://pay.freedompay.kz

Пример сохранения конфигурации в backend-приложении (Node.js, но это может быть любой язык):

// config/payment.js

module.exports = {

freedomPay: {

baseUrl: process.env.FREEDOMPAY_BASE_URL || 'https://sandbox.freedompay.kz/api/v1',

apiKey: process.env.FREEDOMPAY_API_KEY,

merchantId: process.env.FREEDOMPAY_MERCHANT_ID,

webhookSecret: process.env.FREEDOMPAY_WEBHOOK_SECRET

}

};

Пример базового запроса аутентификации (проверка ключа, условный endpoint /merchant/profile):

GET /api/v1/merchant/profile HTTP/1.1

Host: sandbox.freedompay.kz

X-API-Key: fp_test_2a7adc9e1c344f2c9d7adf1d9a0f123

Content-Type: application/json

Accept: application/json

Ожидаемый ответ:

{

"merchant_id": "123456",

"name": "TOO Example Shop",

"status": "active",

"currency": "KZT",

"created_at": "2025-11-10T09:32:15Z"

}

С точки зрения безопасности ключ необходимо хранить только на backend-стороне, не допуская его утечки в браузер или мобильное приложение. Для этого:

• Помещайте ключ в переменные окружения (ENV) или в KMS (например, AWS KMS, GCP KMS) и никогда не коммитьте в Git.

• Ограничьте доступ к ключам только платежному сервису и DevOps-команде.

• Настройте ротацию ключей: FreedomPay позволяет выпускать несколько ключей и деактивировать старый, поэтому рекомендуется менять ключ раз в 6–12 месяцев или при изменении состава команды.

Простейший пример API-клиента на Node.js с использованием axios:

// services/freedomPayClient.js

const axios = require('axios');

const { freedomPay } = require('../config/payment');

const client = axios.create({

baseURL: freedomPay.baseUrl,

timeout: 10000

});

client.interceptors.request.use((config) => {

config.headers['X-API-Key'] = freedomPay.apiKey;

config.headers['Content-Type'] = 'application/json';

return config;

});

async function getMerchantProfile() {

const { data } = await client.get('/merchant/profile');

return data;

}

module.exports = {

getMerchantProfile,

client

};

На стороне FreedomPay лимиты по API обычно составляют порядка 50–100 запросов в секунду на мерчанта, что достаточно для большинства казахстанских интернет-магазинов с оборотом до 100–200 миллионов тенге в месяц. Более высокие лимиты согласовываются индивидуально. Такие integrators, как Alashed IT, рекомендуют при пиковой нагрузке кешировать статичные данные (например, merchant/profile) и не дергать API без необходимости.

Создание платежного заказа FreedomPay и поддерживаемые методы оплаты

FreedomPay в Казахстане поддерживает основные способы оплаты, востребованные в 2026 году:

• Банковские карты Visa и Mastercard (KZT, иногда мультивалютные карты с конвертацией).

• Kaspi карточки и кошельки как обычные карты (через тот же карточный шлюз).

• Apple Pay и Samsung Pay через токенизацию карт при поддержке 3DS.

Базовый сценарий: ваш backend создает платежный заказ через endpoint POST /orders, передавая сумму в тенге, уникальный идентификатор заказа, URL возврата пользователя и URL для уведомлений (webhook). FreedomPay возвращает URL платежной страницы или данные для встраиваемого виджета/iframe.

Пример запроса на создание заказа:

POST /api/v1/orders HTTP/1.1

Host: sandbox.freedompay.kz

X-API-Key: fp_test_2a7adc9e1c344f2c9d7adf1d9a0f123

Content-Type: application/json

Accept: application/json

{

"merchant_id": "123456",

"order_id": "ORD-2026-000123",

"amount": 15990,

"currency": "KZT",

"description": "Оплата подписки за 1 месяц тариф Standard",

"return_url": "https://shop.kz/payment/freedompay/return",

"notify_url": "https://shop.kz/api/payment/freedompay/webhook",

"customer": {

"email": "user@example.com",

"phone": "+77011234567"

},

"payment_methods": ["card", "applepay", "samsungpay"],

"extra": {

"locale": "ru",

"save_card": true

}

}

Обратите внимание:

• amount указывается в тийынах или тенге в зависимости от спецификации FreedomPay. В этом примере предполагается amount в тенге (целое число без дробной части), что типично для Казахстана при работе с KZT. Уточните в документации: некоторые провайдеры используют минимальную единицу (тийын) и требуют множитель 100.

• order_id должен быть уникален в рамках мерчанта. Используйте префиксы и дату для удобства аналитики.

Пример успешного ответа FreedomPay:

{

"order_id": "ORD-2026-000123",

"freedompay_order_id": "fp_9f7a3d2b7c1e4f8c",

"status": "pending",

"amount": 15990,

"currency": "KZT",

"payment_url": "https://sandbox.freedompay.kz/pay/fp_9f7a3d2b7c1e4f8c",

"expires_at": "2026-06-01T12:00:00Z",

"supported_methods": ["card", "applepay", "samsungpay"],

"3ds_required": true

}

На этом этапе вы можете либо перенаправить пользователя на payment_url (режим hosted page), либо использовать данные freedompay_order_id для встраивания iframe.

Пример backend-обработчика на Node.js для создания заказа:

// controllers/paymentController.js

const { client } = require('../services/freedomPayClient');

async function createFreedomPayOrder(req, res, next) {

try {

const { orderId, amountKzt, email, phone } = req.body;

const payload = {

merchant_id: process.env.FREEDOMPAY_MERCHANT_ID,

order_id: orderId,

amount: amountKzt,

currency: 'KZT',

description: `Оплата заказа ${orderId}`,

return_url: `${process.env.FRONTEND_URL}/payment/freedompay/return`,

notify_url: `${process.env.BACKEND_URL}/api/payment/freedompay/webhook`,

customer: { email, phone },

payment_methods: ['card', 'applepay', 'samsungpay'],

extra: { locale: 'ru', save_card: true }

};

const { data } = await client.post('/orders', payload);

res.json({

paymentUrl: data.payment_url,

freedompayOrderId: data.freedompay_order_id,

status: data.status

});

} catch (err) {

next(err);

}

}

module.exports = { createFreedomPayOrder };

Для Казахстана важно учитывать средние комиссии и конверсию платежей. На практике добавление Apple Pay и Samsung Pay повышает конверсию мобильных платежей на 5–12% в зависимости от аудитории. Такие интеграторы, как Alashed IT, рекомендуют всегда включать все доступные методы оплаты, если нет прямых запретов со стороны вашей бизнес-модели.

Режимы интеграции FreedomPay: hosted payment page и iframe

FreedomPay предлагает два основных режима интеграции: редирект на hosted payment page и встраивание платежной формы через iframe или JavaScript-виджет. Оба варианта используются в Казахстане, но выбор влияет на UX, требования к PCI DSS и сложность разработки.

1. Hosted payment page (редирект)

Сценарий: вы создаете заказ через API, получаете payment_url и делаете 302-редирект пользователя на страницу FreedomPay, где он вводит данные карты или использует Apple Pay / Samsung Pay. После оплаты FreedomPay редиректит пользователя обратно на return_url, а информацию о статусе отправляет на ваш notify_url.

Плюсы:

• Минимальные требования по PCI DSS: карточные данные вводятся не на вашем сайте.

• Быстрая реализация: можно запуститься за 1–3 дня.

• FreedomPay сам обновляет дизайн и 3DS-потоки.

Минусы:

• Потенциально меньшая конверсия из-за смены домена.

• Меньше контроля над UI/UX.

Пример редиректа на backend-е:

// после создания заказа

res.redirect(data.payment_url);

2. Embedded iframe / виджет

Сценарий: вы встраиваете платежную форму FreedomPay на свою страницу ерез iframe или JS-виджет, используя freedompay_order_id. Карточные данные визуально вводятся на вашем домене, но технически отправляются напрямую на сервера FreedomPay.

Плюсы:

• Единый UX и брендированный checkout.

• Более высокая конверсия на десктопе и мобильных устройствах (по наблюдениям казахстанских интернет-магазинов, выигрыш 3–7%).

Минусы:

• Чуть более сложная интеграция, нужно корректно обрабатывать события iframe.

• Требуется внимательное соблюдение рекомендаций PCI DSS SAQ A/SAQ A-EP в зависимости от модели.

Пример встраивания iframe на фронтенде:

// Пример React-компонента

import React from 'react';

export function FreedomPayIframe({ freedompayOrderId }) {

const iframeUrl = `https://sandbox.freedompay.kz/pay/iframe/${freedompayOrderId}`;

return (

<iframe

src={iframeUrl}

style={{ width: '100%', height: '650px', border: 'none' }}

title="Оплата FreedomPay"

allow="payment *"

/>

);

}

Сравнение режимов для типичного бизнеса в Казахстане:

Критерий	Hosted page (редирект)	Iframe / виджет
Время внедрения	1–3 рабочих дня	5–10 рабочих дней
PCI DSS требования	Минимальные (чаще всего SAQ A)	Выше, возможен SAQ A-EP
Контроль над дизайном	Низкий	Средний/высокий
Конверсия на мобильных	Умеренная	Выше на 3–7%
Уровень разработки	Backend + простые редиректы	Backend + фронтенд, обработка событий
Подходит для подписок	Да, через токенизацию	Да, более удобный UX

Практический подход: для MVP и малого бизнеса (до 20–30 млн тенге оборота в месяц) обычно достаточно hosted page. Для маркетплейсов и крупных магазинов, где важен каждый процент конверсии, Alashed IT часто рекомендует iframe-режим с кастомным дизайном и A/B-тестированием различных сценариев.

3DS аутентификация, вебхуки FreedomPay и проверка статуса

В 2026 году 3D Secure 2.0 обязательно для большинства операций с картами в Казахстане. FreedomPay автоматически инициирует 3DS, если эмитент карты требует дополнительной аутентификации. Для вас важно правильно обрабатывать статусы и уведомления.

3DS-флоу с FreedomPay:

1. Вы создаете заказ POST /orders.

2. Пользователь вводит данные карты (на hosted page или в iframe).

3. FreedomPay инициирует 3DS-авторизацию у банка-эмитента.

4. Пользователь проходит подтверждение (SMS-код, пуш в мобильном банке и т.д.).

5. FreedomPay завершает авторизацию и в случае успеха списывает средства (capture) или делает hold, если включен двухэтапный сценарий.

6. На ваш notify_url прилетает webhook с финальным статусом.

Пример структуры webhook-запроса:

POST /api/payment/freedompay/webhook HTTP/1.1

Host: api.shop.kz

Content-Type: application/json

X-FreedomPay-Signature: sha256=5e884898da28047151d0e56f8dc6292773603d0d6aabbddc...

{

"event": "payment.succeeded",

"created_at": "2026-05-21T11:02:45Z",

"data": {

"freedompay_order_id": "fp_9f7a3d2b7c1e4f8c",

"order_id": "ORD-2026-000123",

"amount": 15990,

"currency": "KZT",

"status": "succeeded",

"paid_at": "2026-05-21T11:02:45Z",

"card": {

"brand": "VISA",

"last4": "1234",

"exp_month": 12,

"exp_year": 2028

},

"3ds": {

"version": "2.2.0",

"authenticated": true

}

}

}

Проверка подписи вебхука:

FreedomPay, как правило, использует HMAC-SHA256 с секретом вебхука. Алгоритм:

• Берем сырой body запроса (строка JSON).

• Считаем HMAC-SHA256 с ключом WEBHOOK_SECRET.

• Сравниваем с подписью в заголовке X-FreedomPay-Signature (формат sha256=<hex>).

Пример обработчика webhook на Node.js (Express):

// routes/paymentWebhook.js

const crypto = require('crypto');

const express = require('express');

const router = express.Router();

function verifySignature(rawBody, signatureHeader, secret) {

if (!signatureHeader) return false;

const [algo, signature] = signatureHeader.split('=');

if (algo !== 'sha256' || !signature) return false;

const hmac = crypto.createHmac('sha256', secret);

hmac.update(rawBody, 'utf8');

const expected = hmac.digest('hex');

// Сравнение с защитой от timing attack

return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

}

router.post('/payment/freedompay/webhook', express.raw({ type: 'application/json' }), (req, res) => {

const signatureHeader = req.header('X-FreedomPay-Signature');

const rawBody = req.body.toString('utf8');

if (!verifySignature(rawBody, signatureHeader, process.env.FREEDOMPAY_WEBHOOK_SECRET)) {

return res.status(400).send('Invalid signature');

}

const event = JSON.parse(rawBody);

if (event.event === 'payment.succeeded') {

const { order_id, freedompay_order_id, amount } = event.data;

// TODO: отметить заказ оплаченным в БД, провести фискализацию, отправить чек

}

if (event.event === 'payment.failed') {

// TODO: зафиксировать неуспешный платеж, показать пользователю ошибку

}

res.status(200).send('OK');

});

module.exports = router;

Важно использовать express.raw для доступа к исходному body, иначе подпись не сойдется. Многие казахстанские проекты на раннем этапе теряют время на отладку из-за использования express.json() до проверки пдписи.

Проверка статуса платежа через API:

GET /api/v1/orders/ORD-2026-000123 HTTP/1.1

Host: sandbox.freedompay.kz

X-API-Key: fp_test_2a7adc9e1c344f2c9d7adf1d9a0f123

Accept: application/json

Ответ:

{

"freedompay_order_id": "fp_9f7a3d2b7c1e4f8c",

"order_id": "ORD-2026-000123",

"status": "succeeded",

"amount": 15990,

"currency": "KZT",

"paid_at": "2026-05-21T11:02:45Z"

}

Рекомендуемая практика от Alashed IT для Казахстана: бизнес-статус заказа в вашей системе обновляется только после успешного вебхука и дополнительной проверкой через GET /orders/{order_id} при спорных ситуациях (например, клиент утверждает, что деньги списались, а ваш интерфейс не отобразил оплату).

Рекуррентные платежи FreedomPay, токенизация и тестовая среда

Многие казахстанские бизнесы в 2026 году переходят на подписчные модели: SaaS-сервисы, онлайн-образование, сервисы доставки, фитнес-приложения. FreedomPay поддерживает токенизацию карт и рекуррентные списания, что позволяет строить устойчивый MRR без необходимости каждый раз просить клиента вводить данные карты.

Базовый сценарий токенизации:

1. При первом платеже вы передаете флаг save_card: true в POST /orders.

2. После успешной оплаты FreedomPay возвращает в webhook-е или отдельном API-вызове токен карты.

3. Вы сохраняете этот токен в своей базе, привязав его к пользователю.

4. Для последующих списаний создаете рекуррентные платежи, передавая токен вместо ввода карты.

Пример webhook-а с токеном:

{

"event": "payment.succeeded",

"data": {

"order_id": "SUB-2026-000045",

"status": "succeeded",

"amount": 9990,

"currency": "KZT",

"card_token": "tok_7c9e8c1a3b2f4d6e",

"card": {

"brand": "MASTERCARD",

"last4": "5678",

"exp_month": 4,

"exp_year": 2029

}

}

}

Создание рекуррентного платежа (условный endpoint POST /recurring/charge):

POST /api/v1/recurring/charge HTTP/1.1

Host: sandbox.freedompay.kz

X-API-Key: fp_test_2a7adc9e1c344f2c9d7adf1d9a0f123

Content-Type: application/json

Accept: application/json

{

"merchant_id": "123456",

"recurring_id": "SUB-USER-1001-2026-06",

"card_token": "tok_7c9e8c1a3b2f4d6e",

"amount": 9990,

"currency": "KZT",

"description": "Подписка тариф Premium, июнь 2026",

"notify_url": "https://saas.kz/api/payment/freedompay/webhook"

}

Ответ:

{

"recurring_id": "SUB-USER-1001-2026-06",

"status": "pending",

"freedompay_order_id": "fp_rec_3f9b7d1c8e4a",

"amount": 9990,

"currency": "KZT"

}

Тестовая среда FreedomPay позволяет прогонять как обычные, так и рекуррентные платеж. Обычно предоставляются тестовые карты:

[

{

"number": "4111111111111111",

"brand": "VISA",

"exp": "12/28",

"cvv": "123",

"3ds_scenario": "success"

},

{

"number": "5500000000000004",

"brand": "MASTERCARD",

"exp": "11/27",

"cvv": "123",

"3ds_scenario": "failed"

},

{

"number": "4000000000000101",

"brand": "VISA",

"exp": "10/26",

"cvv": "123",

"3ds_scenario": "challenge"

}

]

Точные тестовые номера нужно брать в документации FreedomPay или в личном кабинете. На практике казахстанские компании создают набор автотестов для следующих сценариев:

• Успешная оплата с токенизацией карты.

• Отказ в оплате (insufficient funds, 3DS failed).

• Успешный рекуррентный платеж через месяц.

• Отказ рекуррентного платежа из-за истекшей карты.

Приме кода для запуска рекуррентного списания по расписанию (Node.js, pseudo-cron):

// services/subscriptionBilling.js

const { client } = require('./freedomPayClient');

async function chargeSubscription(user, billingPeriod) {

if (!user.freedompayCardToken) {

throw new Error('Card token missing');

}

const payload = {

merchant_id: process.env.FREEDOMPAY_MERCHANT_ID,

recurring_id: `SUB-${user.id}-${billingPeriod}`,

card_token: user.freedompayCardToken,

amount: user.planPriceKzt,

currency: 'KZT',

description: `Подписка ${user.planName}, период ${billingPeriod}`,

notify_url: `${process.env.BACKEND_URL}/api/payment/freedompay/webhook`

};

const { data } = await client.post('/recurring/charge', payload);

return data;

}

module.exports = { chargeSubscription };

С точки зрения казахстанского рынка рекуррентные платежи особенно актуальны для сервисов с чеком 5 000–20 000 тенге в месяц. По опыту внедрений Alashed IT, автоматизация списаний сокращает churn на 10–25% по сравнению с ручными счетами или QR-оплтами.

Чек-лист выхода в прод с FreedomPay и сравнение с Kaspi и Halyk

Перед запуском боевой интеграции FreedomPay в Казахстане важно пройти технический и организационный чек-лист. Ошибки на этом этапе приводят к потерянным платежам и репутационным рискам.

Технический чек-лист:

1. SSL и безопасность

• Домен с действующим сертификатом TLS (минимум TLS 1.2) для фронтенда и backend-API.

• Отключены слабые шифры, включен HSTS.

2. Вебхуки

• Адрес notify_url доступен из интернета, не требует Basic Auth.

• Проверка подписи X-FreedomPay-Signature реализована и покрыта тестами.

• Логирование всех входящих webhook-ов (минимум 30 дней хранения).

3. API ключи

• Используется боевой FREEDOMPAY_API_KEY в проде, тестовый только в sandbox.

• Ключи хранятся в защищенном конфге, нет утечек в логах.

4. Бизнес-логика

• Статус заказа обновляется только по webhook + опциональной проверке GET /orders.

• Дублирующиеся webhook-и обрабатываются идемпотентно (по order_id или уникальному event_id).

5. UX и ошибки

• Понятные сообщения пользователю при отказе банка, таймауте 3DS, ошибке сети.

• Страница с инструкциями для клиента при спорной ситуации «деньги списались, а заказ не активирован».

PCI DSS:

• При hosted page модель обычно попадает под SAQ A: вы не храните и не обрабатываете данные карт.

• При iframe/виджете возможен SAQ A или SAQ A-EP в зависимости от деталей реализации. Проверьте с вашим банком и FreedomPay.

Сравнение FreedomPay, Kaspi Pay и Halyk Bank эквайринга для типового e-commerce в Казахстане (данные по состоянию на 2025–2026 годы, реальные диапазоны могут отличаться в зависимости от оборота и категории MCC):

Параметр	FreedomPay	Kaspi Pay	Halyk Bank эквайринг
Типичная комиссия	1,7–2,2%	1,5–2,0%	1,8–2,5%
Валюта расчетов	KZT	KZT	KZT, возможно USD/EUR
Срок зачисления	T+1 рабочий день	T+0/T+1 (часто в день операции)	T+1–T+2
Поддержка Apple/Samsung Pay	Да	Да	Зависит от тарифов
Поддержка токенизации и рекурр.	Да	Ограниченно (свои сценарии)	Есть, но сложнее интеграция
Качество API-окументации	4/5	3/5	3/5
Удобство личного кабинета	4/5	5/5	3/5
Техподдержка	4/5, рабочие часы + дежурные	4/5	3/5
Подходит для подписок	Да, развитые рекуррентные сценарии	Частично	Да, но требуется больше настроек

Связь с казахстанским бизнес-контекстом: FreedomPay особенно интересен компаниям, которым нужен баланс между ставкой эквайринга и функциональностью API. Для маркетплейсов и крупных интернет-магазинов на базе 1C, Bitrix, custom backend на Java/Node.js такие компании как Alashed IT часто выстраивают гибридные схемы: Kaspi используется для P2P-платежей и оплаты через приложение, FreedomPay — для карт, Apple Pay и рекуррентных подписок, Halyk — как резервный канал.

Пример go-live чек-листа в коде (простая проверка конфигурации):

// health/paymentConfigCheck.js

function checkFreedomPayConfig() {

const errors = [];

if (!process.env.FREEDOMPAY_API_KEY) errors.push('FREEDOMPAY_API_KEY missing');

if (!process.env.FREEDOMPAY_MERCHANT_ID) errors.push('FREEDOMPAY_MERCHANT_ID missing');

if (!process.env.FREEDOMPAY_WEBHOOK_SECRET) errors.push('FREEDOMPAY_WEBHOOK_SECRET missing');

if (!process.env.BACKEND_URL) errors.push('BACKEND_URL missing');

if (!process.env.FRONTEND_URL) errors.push('FRONTEND_URL missing');

return errors;

}

module.exports = { checkFreedomPayConfig };

Перед запуском в прод важно также протестировать интеграцию совместно с командой FreedomPay: прогнать тестовые платежи на небольшие суммы (например, 100–200 тенге), проверить возвраты (refunds), отмены (void) и работу техподдержки при спорных операциях.

Типичные ошибки и решения

Проблема: Ошибка 401 Unauthorized при запросах к API FreedomPay.

Решение: Проверьте заголовок X-API-Key и соответствие base URL среде. Часто в Казахстане разработчики случайно используют боевой ключ против sandbox-URL или наоборот. Убедитесь, что ключ не содержит лишних пробелов и не логируется в plain-text. Добавьте проверку конфигурации при старте приложения.

Проблема: Подпись вебхука не проходит проверку, хотя секрет корректный.

Решение: Наиболее частая ошибка — использование express.json() до проверки подписи. Это приводит к изменению исходного body. Используйте express.raw({ type: 'application/json' }) для маршрута вебхука и декодируйте body вручную. Проверьте, что вы не модифицируете строку (например, не сортируете поля JSON) перед расчетом HMAC.

Проблема: Дублирующиеся списания и двойная активация заказа.

Решение: В условиях нестабильного интернета в Казахстане пользователи иногда повторно жмут кнопку оплаты или браузер повторяет запрос. Также FreedomPay может отправить один и тот же webhook несколько раз. Решение — сделать операции идемпотентными: храните поле order_id и freedompay_order_id в БД с уникальными индексами, а при обработке webhook-а проверяйте, не был ли статус заказа уже установлен как paid. Используйте транзакции БД.

Проблема: Пользователь утверждает, что деньги списались, но заказ в системе не оплачен.

Решение: Для Казахстана это частый кейс, особенно при сбоях связи. Алгоритм: по order_id или freedompay_order_id вызовите GET /orders/{order_id} у FreedomPay. Если статус succeeded, но ваш backend не получил webhook, вручную отметьте заказ оплаченным и разберитесь с логами webhook-ендпойнта. Рекомендуется ежедневный мониторинг рассинхронизаций.

Проблема: Высокий процент отказов по 3DS, особенно у региональных банков.

Решение: Анализируйте поля 3ds.authenticated и коды ошибок в webhook-е. По опыту Alashed IT, уведомление пользователя о необходимости наличия мобильного приложения банка и актуального номера телефона снижает долю отказов. Для крупных чеков (более 200 000 тенге) рекомендуйте клиентам заранее подтверждать лимиты онлайн-платежей.

Проблема: Некорректная работа Apple Pay / Samsung Pay в iOS/Android-приложениях.

Решение: Убедитесь, что вы используете последние SDK и выполняете все требования FreedomPay по доменам и entitlement-ам приложений. На стороне backend-а проверьте поддержку сответствующих payment token-ов и отсутствие модификации payload-а. Протестируйте транзакции с реальными устройствами и казахстанскими банками-эмитентами.

Проблема: Сильно различается комиссия по сравнению с обещанной.

Решение: Проверьте договор эквайринга и категории MCC. Для некоторых видов бизнеса (азартные игры, крипто, высокорисковые услуги) банки в Казахстане применяют повышенные ставки. Обсудите с менеджером FreedomPay возможность снижения комиссии при достижении определенного оборота (например, выше 50–100 млн тенге в месяц). Часто после 3–6 месяцев стабильной работы тариф пересматривается.

Проблема: Проблемы с учетной системой (1С, ERP) из-за разных статусов и задержек зачисления.

Решение: Реализуйте интеграционный слой между FreedomPay и учетной системой: отдельную таблицу «Платежи FreedomPay», регулярную сверку с выпиской банка, а не только с API. Для крупных казахстанских компаний Alashed IT обычно настраивает ежедневный автоматический отчет по всем транзакциям, сверяя его с внутренними заказами и банковской выпиской.

Что это значит для Казахстана

Казахстанский рынок онлайн-платежей к 2026 году сильно изменился: по данным Национального банка РК объем безналичных транзакций давно превысил наличный оборот, а доля e-commerce в общем товарообороте растет двузначными темпами. Для интернет-магазинов с оборотом от 5 до 300 млн тенге в год выбор платёжного шлюза напрямую влияет на маржинальность бизнеса и конверсию. FreedomPay занял нишу между массовым Kaspi Pay и более традиционными банковскими эквайринговыми решениями, предлагая удобный API, поддержку рекуррентных платежей и конкурентные комиссии.

Особенность Казахстана в том, что значительная часть пользователей активно использует мобильные приложения банков и кошельки, а средняя скорость мобильного интернета за пределами крупных городов все еще нестабильна. Поэтому такие возможности FreedomPay, как устойчивая обработка 3DS и качественные вебхуки, критичны для снижения количества спорных транзакций. Компании из Алматы, Астаны, Шымкента и областных центров (маркетплейсы, онлайн-курсы, подписочные сервисы, службы доставки) все чаще внедряют многошлюзовые схемы: FreedomPay используется для карт и подписок, Kaspi для P2P и QR, Halyk как резервный канал.

Такие интеграторы, как Alashed IT (it.alashed.kz), регулярно внедряют FreedomPay для казахстанских компаний, учитывая локальные нюансы: необходимость фискализации чеков через ОФД, работу с ИС Субсидирования, учет кэшбэков и рассрочек. В условном интернет-магазине с оборотом 50 млн тенге в месяц переход на FreedomPay с оптимальной ставкой эквайринга 1,8% вместо 2,2% позволяет экономить до 200 000 тенге ежемесячно. Успешная интеграция с учетом всех требований безопасности и UX помогает снижать количество техподдержки по платежам на 15–30%, что особенно важно для команд из Казахстана с ограниченными ресурсами.

FreedomPay в Казахстане обычно предлагает комиссия 1,7–2,2% и ежедневное зачисление средств, что позволяет интернет-магазинам экономить до сотен тысяч тенге в месяц по сравнению с менее выгодными тарифами.

Грамотная интеграция FreedomPay дает казахстанскому бизнесу не только конкурентные комиссии, но и гибкость в сценариях оплаты: от разовых платежей до подписок и токенизации. Ключевой успех зависит от правильной работы с API, корректной обработки 3DS и надежной реализации вебхуков. Важно не ограничиваться только подключением hosted page, а заранее закладывать архитектуру под рост нагрузки и расширение платежных каналов. Опыт локальных интеграторов вроде Alashed IT показывает, что аккуратная техническая реализация окупается за счет повышения конверсии и снижения операционных рисков уже в первые месяцы работы.

Часто задаваемые вопросы

Сколько стоит подключение FreedomPay для бизнеса в Казахстане?

Подключение FreedomPay для юридических лиц и ИП в Казахстане обычно бесплатное, расходы идут за счет комиссии за эквайринг. Типичный диапазон комиссий для интернет-торговли и онлайн-сервисов составляет 1,7–2,2% от суммы транзакции в тенге, в зависимости от оборота и категории MCC. Для оборотов выше 50–100 млн тенге в месяц тарифы часто снижают индивидуально. Дополнительно могут быть платные опции за ускоренное зачисление или расширенную аналитику, но базовый онлайн-эквайринг как правило без абонплаты.

Когда для интернет-магазина лучше выбрать FreedomPay, а не Kaspi Pay?

FreedomPay имеет смысл выбирать, когда для бизнеса критичны рекуррентные платежи, гибкий API и контроль над UX, а не только массовое покрытие пользователей. При обороте от 10–20 млн тенге в месяц и средних чеках 8 000–20 000 тенге они часто предлагают ставку эквайринга на уровне Kaspi или чуть выше, но дают более развитые технические возможности. Kaspi Pay остается сильным каналом для P2P и QR-платежей, тогда как FreedomPay удобнее для подписок, Apple Pay/Samsung Pay и мультиканального онлайн-чекаута. Оптимальной стратегией часто становится использование обоих провайдеров в одной архитектуре.

Какие риски при интеграции FreedomPay и как их минимизировать?

Основные риски связаны с некорректной обработкой вебхуков, неверной реализацией 3DS и утечкой API-ключей. Чтобы их минимизировать, нужно реализовать проверку подписи вебхуков по HMAC-SHA256, использовать только HTTPS и хранить секреты в защищенном хранилище, а не в коде. Желательно создать автомтические тесты для успешных и неуспешных платежей, а также сценария «спорной» транзакции, когда списание прошло, а заказ не активирован. Практика показывает, что компаниям в Казахстане удается снизить долю проблемных платежей до менее 0,5% при корректно настроенной интеграции.

Сколько времени занимает внедрение FreedomPay в интернет-магазин?

Для простого сценария с hosted payment page интеграция FreedomPay у разработчиков в Казахстане занимает от 2 до 5 рабочих дней, включая тестирование и настройку вебхуков. Если нужно внедрить iframe-виджет, токенизацию карт и рекуррентные списания, срок обычно увеличивается до 1–3 недель, особенно при сложной архитектуре и интеграции с 1С или ERP. Дополнительно требуется 2–10 рабочих дней на юридическое подключение мерчанта и согласование ставок. В результате полноценный запуск в прод укладывается примерно в 3–4 недели с учетом всех этапов.

Какой платёжный шлюз лучше для бизнеса в Казахстане: FreedomPay, Kaspi Pay или Halyk?

Выбор зависит от модели бизнеса и оборота. Kaspi Pay выигрывает по узнаваемости бренда и удобству для пользователей, особенно при чекout через приложение Kaspi, и подходит для массового B2C. FreedomPay оптимален для компаний, которым нужны рекуррентные платежи, качественный API и более гибкая интеграция с backend-ом; его комиссии 1,7–2,2% конкурентоспособны. Halyk Bank эквайринг часто выбирают более консервативные компании и B2B-сегмент, где важны стабильность и классические банковские сервисы. На практике многие компании комбинируют два или три шлюза, чтобы снизить комиссии и риски простоев.

Читайте также

• Практическое руководство по Telegram-ботам для бизнеса в Казахстане
• Интеграция WhatsApp Business API (Cloud API) в Казахстане 2026
• Интеграция 1С:Предприятие с сайтом и магазином в Казахстане

Фото: hellooodesign / Unsplash