Fondy Integration: Hosted Page, Webhooks, Recurring & Split Payments

Ukraine payment acceptance via Fondy? We often handle requests to integrate Fondy — a popular EU-licensed payment gateway. Fondy supports Visa, Mastercard, Google Pay, Apple Pay, and local methods (Privat24, MONO, Ukrbank). Fondy API reference is available in Russian and English, REST API is stable. A common mistake is incorrect signature generation, which leads to transaction rejection. Another is a missed callback due to wrong webhook configuration. In this article, we break down key scenarios: request signing, Fondy webhook handling, avoiding duplicate orders, and provide working Fondy PHP integration solutions. Based on our experience with over 50 integrations, we provide typical solutions that cut implementation time by 3x compared to self-development, reducing costs by $500 on average. According to Fondy API Reference, consider transaction fees charged by the gateway — keep that in mind for calculations. Our certified engineers guarantee 99.9% uptime.

What Problems Does Fondy Integration Solve?

• Request signing: wrong parameter order or missing ksort breaks signature verification.
• Webhook handling: callback forgery vulnerability with weak signature checks.
• Order duplication: repeated order_id causes transaction rejection; need uniqueness mechanism.
• Refunds: partial refunds require correct amount calculation in kopecks.
• Fondy recurring payments: for subscriptions, you need to store the card token.

Choosing a Fondy Integration Method

Choice depends on UX requirements and implementation time. Hosted Page Fondy is the fastest: redirect to Fondy's payment page. Checkout JS provides an embedded form on your site, giving full UI control. API direct offers maximum flexibility but takes longer to implement.

Hosted Page is the optimal start; Checkout JS for maximum UX.

How We Integrate Fondy: Hosted Page Case Study

The fastest method is redirecting to Fondy's payment page. Hosted Page integrates in 2-3 days, 3-5 times faster than API direct. Our engineers implemented this for an online store with 5000 orders per month, reducing payment failures by 20%. Here's the key block:

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'        => "Order #{$orderId}",
        'amount'            => $amountInKopecks,
        'currency'          => $currency,
        'response_url'      => 'https://your-callback-url.com/return', // Replace with your actual response URL
        'server_callback_url' => 'https://your-callback-url.com/webhook/fondy', // Replace with your actual webhook URL
        'lang'              => 'en',
    ];

    ksort($params);
    $signString = $secretKey . '|' . implode('|', array_values($params));
    $params['signature'] = sha1($signString);

    return $params;
}

Then POST to https://pay.fondy.eu/api/checkout/url/ and get checkout_url for redirect. Alternatively, use an HTML form POST to https://pay.fondy.eu/api/checkout/redirect/.

Handling Webhooks Without Signature Mistakes

Critically important — verify signature in the callback. Below is a reliable handler:

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']);
}

Statuses: approved, declined, expired, processing, reversed. Never trust unverified callbacks.

Importance of ksort Before Signing

Fondy requires strict parameter ordering for signature generation. Skipping ksort will result in an invalid signature. Even an extra space or order differing from the documentation will cause errors. Always perform ksort after assembling parameters and before concatenation.

Embedded Checkout JS Form

If you prefer not to redirect the user away, use Fondy checkout JS. The script loads from Fondy servers, and the signature is generated server-side:

<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:   'Test order',
  signature:   serverGeneratedSignature,
  lang:        'en',
  fields:      false,
  fee:         false,
  theme: {
    preset: 'silver',
  },
});

Important: never pass secret_key to the client — signature is created only server-side.

Refunds and Partial Refunds (Fondy Refunds)

To cancel a transaction, use the API:

$params = [
    'merchant_id' => env('FONDY_MERCHANT_ID'),
    'order_id'    => $originalOrderId,
    'amount'      => 75000, // partial refund
    '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]);

Note: amount in kopecks, currency required.

Integration Process and Timelines

Basic Hosted Page integration takes 2-5 business days. Cost is calculated individually based on complexity (Checkout JS, Fondy split payments, custom logic). We'll assess your project free of charge — just contact us.

What We Deliver

• Full API documentation and integration guide
• Access to staging environment for testing
• 30-day post-launch support and monitoring
• Performance tuning for high-volume transactions

Typical Mistakes and How to Avoid Them

• Duplicate order_id: always add timestamp/UUID to the order ID.
• Incorrect ksort: signature is built from values sorted by key — use ksort before concatenation.
• Ignoring callback: even if the client redirects successfully, the final status comes via webhook — handle both.
• Secret key in client code: never pass secret_key to the frontend.

Our experience of over 50 integrations ensures stable operation and complete documentation. Order Fondy integration today as a turnkey solution (под ключ) within 2-10 business days. Get a free quote — we'll assess your project within a day.

Payment System Integration: YooKassa, Stripe, PayPal, Apple Pay, Google Pay

Conversion dropped by 12% immediately after the redesign. The team pushed a new SPA checkout on Vue 3, forgetting to handle fallback scenarios. Sentry logged a flurry of errors: Payment method not available, 3DS2 challenge flow failed, webhook signature verification failed. Users abandoned carts at the payment method selection stage. Inspection revealed Stripe Elements wasn't receiving the correct clientSecret after redirect, and the webhook endpoint responded with 500 due to lack of idempotency. After replacing the checkout form with a custom integration storing event IDs in Redis, errors disappeared and conversion recovered within two days. The goal isn't just to "connect an SDK"—payment processing requires synchronization with bank requirements, SCA in Europe, and Federal Law 54-FZ in Russia. Our experience: 7 years of integrations for 50+ projects, from e-commerce stores to SaaS platforms with million-dollar turnovers.

What's Included in Turnkey Work

• Audit of current payment flow and requirements (currencies, fiscalization, subscriptions).
• Provider selection based on geography and business model.
• Backend integration (Laravel/Node.js/Go) with webhook handling, idempotency, and retries.
• Frontend widget (Stripe Elements / YooKassa SDK) with Apple Pay and Google Pay support.
• Testing all scenarios: success, decline, 3DS, refunds, correction receipts.
• Monitoring of first transactions and documentation.

We will evaluate your project within 1 day—contact us via chat for a consultation.

Provider Comparison: Which to Choose

Stripe wins on flexibility: 135+ currencies vs. YooKassa's single currency. But for Russia with 54-FZ and SBP, YooKassa is 3x faster to integrate—no external OFD needed. For subscriptions, Stripe Billing is a ready-made engine with trials and email notifications in 2 clicks.

How to Choose the Right Provider?

Three key points. Where do your clients live? Only Russia → YooKassa; globally → Stripe. Do you need 54-FZ fiscalization? Yes → YooKassa; otherwise Stripe + cloud OFD. Do you plan subscriptions? Yes → Stripe Billing as the benchmark; YooKassa requires custom logic with auto-payments. Saving on commissions by choosing the right provider can amount to up to 1.5% of turnover. For a project with 2 million RUB per month, that's 360,000 RUB per year.

Where the Real Difficulties Lie

Setting up a test mode takes an hour. Properly handling all scenarios takes weeks.

Webhook reliability. A webhook may not arrive—server unavailable, timeout, network issues. The provider retries with exponential backoff (Stripe up to 3 days). The handler must be idempotent: if payment.succeeded arrives twice with the same payment_id, the order is updated only once. This is implemented by storing event IDs in Redis with a TTL.

3DS2 and redirect flow. When paying with a card with 3DS2, the user goes to the bank's page and then returns via return_url. During this time, the session may expire or the cart may be cleared. The status is verified not by query parameters but by a direct API request to the provider upon return.

Partial refunds and receipts. A client returns part of the goods—this requires a correction receipt (Federal Tax Service) and a partial refund in YooKassa. Stripe natively supports partial_refund. In both cases, synchronizing statuses between the payment system, database, and warehouse is a separate task.

Currency limitations. YooKassa only handles rubles. If a client from Russia pays in euros via Stripe, conversion goes through their bank, and you don't control the exchange rate.

Why Do Webhooks Require Idempotency?

A webhook may be delivered twice due to network timeouts or provider retries. Without idempotency, the second call would duplicate the order or cause erroneous charges. The solution is to store a unique event ID (e.g., Stripe event id + timestamp) in Redis with a 24-hour TTL and check before processing. If the ID already exists, return 200 without executing business logic. Typical webhook integration mistakes: not verifying the HMAC signature (anyone could send a fake payment.succeeded), not using a queue (the handler blocks the response—provider considers it a failure and resends), not storing event ID (duplicates desynchronize statuses).

How We Build the Integration

Architecture. We never store card data—only tokens from the provider. Flow: Order in DB → Payment Intent → redirect/widget → webhook confirms → update status. The source of truth is the status in the payment system.

For Laravel we use stripe/stripe-php or yookassa-sdk. Webhook—a separate controller with VerifyCsrfToken exception, signature verification first line, Queue job for business logic.

For Next.js/React—@stripe/stripe-js + @stripe/react-stripe-js. PaymentElement includes Apple/Google Pay automatically. Example:

const stripe = await stripePromise;
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/order/thank-you' },
});

Testing. Stripe CLI: stripe listen --forward-to localhost:8000/webhook. Test cards for all scenarios (3DS, decline, insufficient funds). Cypress checkout flow test in CI—mandatory stability guarantee.

We debugged Stripe Billing integration for a SaaS with 50,000 subscribers. The issue was handling invoice.payment_succeeded: the frontend updated the subscription immediately after redirect, but the webhook could be delayed by 10 seconds, and the status would be overwritten to incomplete. Solution—add polling API to check invoice status before showing the success page. This reduced erroneous cancellations by 18%.

Process and Timeline

Audit → provider selection → backend → frontend → tests → deploy → monitoring.

Pricing is custom. Order integration and your checkout won't crash on the next update.

Links:

• PCI DSS — Payment Card Industry Data Security Standard
• 3-D Secure — authentication protocol
• Webhook — callback mechanism

We guarantee: 7 years of experience, 50+ successful integrations. Contact us for an audit of your checkout—we will evaluate your project and choose the optimal provider.