שילוב Fondy: דף מתארח, Webhooks, תשלומים חוזרים ומפוצלים

קבלת תשלומים באוקראינה באמצעות Fondy? אנו מרבים לטפל בבקשות לשילוב Fondy — שער תשלום פופולרי עם רישיון אירופאי. Fondy תומך ב-Visa, Mastercard, Google Pay, Apple Pay, ובאמצעי תשלום מקומיים (Privat24, MONO, Ukrbank). מסמכי ה-API של Fondy זמינים ברוסית ובאנגלית, ו-REST API יציב. טעות נפוצה היא יצירת חתימה שגויה, מה שמוביל לדחיית העסקה. טעות נוספת היא החמצת קריאה חוזרת (callback) עקב הגדרת webhook שגויה. במאמר זה, אנו מפרקים תרחישים מרכזיים: חתימת בקשות, טיפול ב-webhook של Fondy, מניעת הזמנות כפולות, ומספקים פתרונות שילוב PHP עובדים של Fondy. בהתבסס על הניסיון שלנו עם למעלה מ-50 שילובים, אנו מספקים פתרונות אופייניים שמקצרים את זמן היישום פי 3 בהשוואה לפיתוח עצמי, ומפחיתים עלויות ב-500 דולר בממוצע. לפי Fondy API Reference, יש לקחת בחשבון עמלות עסקה שגובה שער התשלום — זכרו זאת בחישובים. המהנדסים המוסמכים שלנו מבטיחים זמינות של 99.9%.

אילו בעיות פותר שילוב Fondy?

• חתימת בקשות: סדר פרמטרים שגוי או חסר 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; } שובר את אימות החתימה.
• טיפול ב-webhook: פגיעות לזיוף קריאות חוזרות עם בדיקות חתימה חלשות.
• כפילות הזמנות: https://pay.fondy.eu/api/checkout/url/ חוזר גורם לדחיית העסקה; יש צורך במנגנון ייחודיות.
• החזרים: החזרים חלקיים דורשים חישוב נכון של הסכום בקופיקות.
• תשלומים חוזרים של Fondy: עבור מנויים, יש צורך לאחסן את אסימון הכרטיס.

בחירת שיטת שילוב Fondy

הבחירה תלויה בדרישות חוויית המשתמש ובזמן היישום. Hosted Page של Fondy הוא המהיר ביותר: הפניה לדף התשלום של Fondy. Checkout JS מספק טופס מוטמע באתר שלך, עם שליטה מלאה בממשק המשתמש. API ישיר מציע גמישות מרבית אך לוקח יותר זמן ליישום.

Hosted Page הוא נקודת הפתיחה האופטימלית; Checkout JS לחוויית משתמש מרבית.

כיצד אנו משלבים את Fondy: מקרה בוחן Hosted Page

השיטה המהירה ביותר היא הפניה לדף התשלום של Fondy. Hosted Page משתלב תוך 2-3 ימים, פי 3-5 מהר יותר מ-API ישיר. המהנדסים שלנו יישמו זאת עבור חנות מקוונת עם 5000 הזמנות בחודש, והפחיתו כשלי תשלום ב-20%. הנה הבלוק המרכזי:

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 אל checkout_url וקבלו https://pay.fondy.eu/api/checkout/redirect/ להפניה. לחלופין, השתמשו בטופס HTML עם POST אל 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']); } .

טיפול ב-Webhooks ללא טעויות חתימה

קריטי ביותר — אמתו את החתימה בקריאה החוזרת. להלן מטפל אמין:

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. לעולם אל תסמכו על קריאות חוזרות לא מאומתות.

חשיבות ksort לפני החתימה

Fondy דורש סדר פרמטרים קפדני ליצירת חתימה. דילוג על ksort יביא לחתימה לא חוקית. אפילו רווח נוסף או סדר שונה מהמתועד יגרמו לשגיאות. בצעו תמיד ksort לאחר הרכבת הפרמטרים ולפני השרשור.

טופס Checkout JS מוטמע

אם אתם מעדיפים לא להפנות את המשתמש החוצה, השתמשו ב-checkout JS של Fondy. הסקריפט נטען משרתי Fondy, והחתימה נוצרת בצד השרת:

<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 ללקוח — החתימה נוצרת רק בצד השרת.

החזרים והחזרים חלקיים (Fondy Refunds)

לביטול עסקה, השתמשו ב-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]);

שימו לב: הסכום בקופיקות, והמטבע נדרש.

תהליך השילוב ולוחות זמנים

שילוב Hosted Page בסיסי אורך 2-5 ימי עסקים. העלות מחושבת באופן אישי לפי מורכבות (Checkout JS, תשלומי חלוקה של Fondy, לוגיקה מותאמת אישית). נבחן את הפרויקט שלכם ללא עלות — פשוט צרו קשר.

מה אנו מספקים

• תיעוד API מלא ומדריך שילוב
• גישה לסביבת staging לבדיקות
• תמיכה וניטור 30 יום לאחר ההשקה
• כוונון ביצועים לעסקאות בנפח גבוה

טעויות נפוצות וכיצד להימנע מהן

• order_id כפול: הוסיפו תמיד חותמת זמן/UUID למזהה ההזמנה.
• ksort שגוי: החתימה נבנית מערכים הממוינים לפי מפתח — השתמשו ב-<script src="https://pay.fondy.eu/static_common/v1/checkout/ipsp.js"></script> לפני השרשור.
• התעלמות מהקריאה החוזרת: גם אם הלקוח מופנה בהצלחה, הסטטוס הסופי מגיע דרך webhook — טפלו בשניהם.
• secret_key בקוד לקוח: לעולם אל תעבירו את secret_key לחזית.

הניסיון שלנו עם למעלה מ-50 שילובים מבטיח פעולה יציבה ותיעוד מלא. הזמינו שילוב Fondy עוד היום כפתרון מפתח (под ключ) תוך 2-10 ימי עסקים. קבלו הצעת מחיר חינם — נבחן את הפרויקט שלכם תוך יום.