Принимаете платежи в Украине? Мы часто сталкиваемся с запросами на интеграцию Fondy — популярного платёжного шлюза с лицензией ЕС. Fondy поддерживает карты Visa, Mastercard, Google Pay, Apple Pay, локальные методы (Приват24, MONO, Укрбанк). Документация на русском и английском, REST API стабилен. Одна из частых ошибок — неправильная генерация подписи, что приводит к отклонению транзакций. Или пропущенный callback из-за неверной настройки webhook. В этой статье разберём ключевые сценарии: подпись запросов, вебхуки, избежание дублей заказов, и покажем рабочие решения на PHP. На основе нашего опыта более 50 интеграций мы подготовили типовые решения, которые сокращают время внедрения до 3 раз по сравнению с самостоятельной разработкой. Согласно Fondy API Reference, комиссия шлюза составляет 2.5% + 2 UAH за транзакцию — учитывайте при расчётах.
Какие проблемы решает интеграция Fondy?
- Подпись запросов: неправильный порядок параметров или отсутствие ksort ломает проверку подписи.
- Обработка вебхуков: уязвимость подделки callback'ов при слабой проверке подписи.
- Дубли заказов: повторный order_id отклоняется транзакция; нужен механизм уникальности.
- Возвраты: частичные возвраты требуют корректного расчёта суммы в копейках.
- Рекуррентные платежи: для подписок нужно сохранять token карты.
Как выбрать метод интеграции Fondy?
Выбор зависит от требований к UX и времени внедрения. Hosted Page — самый быстрый способ: перенаправление на платёжную страницу Fondy. Checkout JS — встроенная форма на вашем сайте, оставляющая полный контроль UI. API direct — максимальная гибкость, но требует больше времени на реализацию.
| Метод | Сложность | Внешний вид | Контроль UI | Время внедрения |
|---|---|---|---|---|
| Hosted Page | Низкая | Страница Fondy | Минимальный | 2-3 дня |
| Checkout JS | Средняя | Ваш сайт | Полный | 5-7 дней |
| API direct | Высокая | Ваш сайт | Полный | 7-14 дней |
Hosted Page — оптимальный старт, Checkout JS — для максимального UX.
Как мы интегрируем Fondy: кейс Hosted Page
Самый быстрый способ — перенаправление на платёжную страницу Fondy. Hosted Page внедряется в 2-3 дня, что в 3-5 раз быстрее, чем API direct. Наши инженеры реализовали это для интернет-магазина с 5000 заказов в месяц. Вот ключевой блок:
function buildFondyPayment(int $orderId, int $amountInKopecks, string $currency = 'UAH'): array
{
$merchantId = env('FONDY_MERCHANT_ID');
$secretKey = env('FONDY_SECRET_KEY');
$params = [
'merchant_id' => $merchantId,
'order_id' => $orderId . '_' . time(),
'order_desc' => "Заказ #{$orderId}",
'amount' => $amountInKopecks,
'currency' => $currency,
'response_url' => 'https://example.com/payment/return',
'server_callback_url' => 'https://example.com/webhook/fondy',
'lang' => 'ru',
];
ksort($params);
$signString = $secretKey . '|' . implode('|', array_values($params));
$params['signature'] = sha1($signString);
return $params;
}
Далее отправляем POST на https://pay.fondy.eu/api/checkout/url/ и получаем checkout_url для редиректа. Альтернатива — HTML-форма с POST на https://pay.fondy.eu/api/checkout/redirect/.
Как обработать вебхук и не ошибиться с подписью?
Критически важный момент — проверка подписи в callback. Ниже пример надёжного обработчика:
public function handleCallback(Request $request): Response
{
$data = $request->all();
$received = $data['signature'];
unset($data['signature']);
$data = array_filter($data, fn($v) => $v !== '' && $v !== null);
ksort($data);
$expected = sha1(env('FONDY_SECRET_KEY') . '|' . implode('|', array_values($data)));
if (!hash_equals($expected, $received)) {
return response('Bad signature', 403);
}
if ($data['order_status'] === 'approved') {
$orderId = (int) explode('_', $data['order_id'])[0];
Order::where('id', $orderId)->update([
'status' => 'paid',
'transaction_id' => $data['payment_id'],
]);
}
return response()->json(['response' => 'accept']);
}
Статусы: approved, declined, expired, processing, reversed. Никогда не доверяйте неверифицированным callback'ам.
Почему важен ksort перед подписью?
Fondy использует строгий порядок параметров для генерации подписи. Если не отсортировать массив по ключам через ksort, подпись будет неверной. Даже лишний пробел или порядок, отличающийся от документации, приведёт к ошибке. Всегда выполняйте ksort после сборки параметров и перед конкатенацией.
Встроенная форма Checkout JS
Если не хотите уводить пользователя со страницы, используйте Checkout JS. Скрипт подгружается с серверов Fondy, а signature генерируется на сервере:
<script src="https://pay.fondy.eu/static_common/v1/checkout/ipsp.js"></script>
$ipsp.get('checkout').config({
merchantId: FONDY_MERCHANT_ID,
amount: 1500,
currency: 'UAH',
orderId: 'order-12345',
orderDesc: 'Тестовый заказ',
signature: serverGeneratedSignature,
lang: 'ru',
fields: false,
fee: false,
theme: {
preset: 'silver',
},
});
Важно: никогда не передавайте secret_key на клиент — signature создаётся только на сервере.
Возвраты и частичные возвраты
Для отмены транзакции используйте API:
$params = [
'merchant_id' => env('FONDY_MERCHANT_ID'),
'order_id' => $originalOrderId,
'amount' => 75000, // частичный возврат
'currency' => 'UAH',
'comment' => 'Customer request',
];
ksort($params);
$params['signature'] = sha1(env('FONDY_SECRET_KEY') . '|' . implode('|', array_values($params)));
Http::post('https://pay.fondy.eu/api/reverse/order/', ['request' => $params]);
Обратите внимание: сумма в копейках, currency обязателен.
Процесс и сроки интеграции
| Этап | Длительность | Результат |
|---|---|---|
| Аналитика | 1-2 дня | Схема процесса оплаты, выбор метода |
| Проектирование | 1-2 дня | Архитектура вебхуков, обработка ошибок |
| Реализация | 2-5 дней | Код, интеграция в CMS/фреймворк |
| Тестирование | 1-2 дня | Транзакции, edge cases |
| Деплой и мониторинг | 1 день | Запуск и поддержка 24 часа |
Базовая интеграция через Hosted Page — от 2 до 5 рабочих дней. Стоимость рассчитывается индивидуально и зависит от сложности (Checkout JS, сплиты, нестандартная логика). Оценим ваш проект бесплатно — напишите нам.
Типичные ошибки и как их избежать
- Повтор order_id: всегда добавляйте timestamp/UUID к ID заказа.
- Неправильный ksort: подпись собирается из значений, отсортированных по ключу — используйте
ksortперед конкатенацией. - Игнорирование callback: даже при успешном редиректе клиента, финальный статус приходит через webhook — обрабатывайте оба.
- Секретный ключ в клиентском коде: никогда не передавайте secret_key на фронтенд.
Наш опыт более 5 лет и 50+ интеграций позволяет гарантировать стабильную работу и полную документацию. Закажите интеграцию Fondy сегодня и получите бесплатную консультацию. Свяжитесь с нами — оценим ваш проект в течение дня.