Інтеграція Fondy: підключення, вебхуки, рекурентні та спліт-платежі

Приймаєте платежі в Україні? Ми часто стикаємося із запитами на інтеграцію Fondy — популярного платіжного шлюзу з ліцензією ЄС. Fondy підтримує картки Visa, Mastercard, Google Pay, Apple Pay, локальні методи (Приват24, MONO, Укрбанк). Документація російською та англійською, REST API стабільний. Одна з частих помилок — неправильна генерація підпису, що призводить до відхилення транзакцій. Або пропущений callback через неправильне налаштування webhook. У цій статті розберемо ключові сценарії: підпис запитів, вебхуки, уникнення дублів замовлень, і покажемо робочі рішення на PHP. На основі нашого досвіду понад 50 інтеграцій ми підготували типові рішення, які скорочують час впровадження до 3 разів порівняно з самостійною розробкою.

Які проблеми вирішує інтеграція Fondy?

• Підпис запитів: неправильний порядок параметрів або відсутність ksort ламає перевірку підпису.
• Обробка вебхуків: вразливість підробки callback'ів при слабкій перевірці підпису.
• Дублі замовлень: повторний order_id відхиляє транзакцію; потрібен механізм унікальності.
• Повернення: часткові повернення вимагають коректного розрахунку суми в копійках.
• Рекурентні платежі: для підписок потрібно зберігати token картки.

Як вибрати метод інтеграції Fondy?

Вибір залежить від вимог до UX та часу впровадження. Hosted Page — найшвидший спосіб: перенаправлення на платіжну сторінку Fondy. Checkout JS — вбудована форма на вашому сайті, що залишає повний контроль UI. API direct — максимальна гнучкість, але потребує більше часу на реалізацію.

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' => 'URL повернення', 'server_callback_url' => 'URL вебхука', '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 обов'язковий.

Процес та терміни інтеграції

Базова інтеграція через Hosted Page — від 2 до 5 робочих днів. Вартість розраховується індивідуально і залежить від складності (Checkout JS, спліти, нестандартна логіка). Оцінимо ваш проект безкоштовно — напишіть нам.

Типові помилки та як їх уникнути

• Повторення order_id: завжди додавайте timestamp/UUID до ID замовлення.
• Неправильний ksort: підпис збирається зі значень, відсортованих за ключем — використовуйте ksort перед конкатенацією.
• Ігнорування callback: навіть при успішному редиректі клієнта, фінальний статус приходить через webhook — обробляйте обидва.
• Секретний ключ у клієнтському коді: ніколи не передавайте secret_key на фронтенд.

Наш досвід понад 5 років та 50+ інтеграцій дозволяє гарантувати стабільну роботу та повну документацію. Замовте інтеграцію Fondy сьогодні та отримайте безкоштовну консультацію. Зв'яжіться з нами — оцінимо ваш проект протягом дня.