שילוב מערכת התשלומים Tinkoff Kassa באתר

שילוב מערכת התשלומים Tinkoff Kassa באתר

בעת שילוב שער התשלומים של Tinkoff, אנו נתקלים לעיתים קרובות בשגיאות יצירת טוקן, כשלים ב-webhook או החזרים שלא פועלים. בואו נפרק כיצד להימנע מבעיות אלו ולהקים קבלת תשלומים יציבה. המערכת מעבדת עסקאות בממוצע פי 1.5 מהר יותר מאגרגטורים עם פרוטוקולי TCP מיושנים, וזמן תגובת ה-API אינו עולה על 200 אלפיות השנייה באחוזון ה-95. מחסנית: PHP 8.3, Laravel 11, PostgreSQL. הניסיון שלנו — מעל 5 שנים, יותר מ-50 פרויקטים מוצלחים, טיפול ביותר מ-10,000 עסקאות ביום. אנו מבטיחים פעולה תקינה גם בעומסי שיא. החיסכון בעלויות העסקאות יכול להגיע ל-40% הודות לניתוב תשלומים אופטימלי. לדוגמה, חנות מקוונת המעבדת 1000 תשלומים של 50$ כל אחד בחודש יכולה לחסוך עד 1,000$ בחודש בעמלות. ה-API של Tinkoff Kassa דורש חתימה על כל בקשה — אחרת תוחזר שגיאה 401.

חיבור Tinkoff Kassa לאתר

קבלת אישורי גישה

לצורך פעולה, יש צורך בשני מפתחות: TerminalKey ו-Password. ניתן לקבל אותם בחשבון האישי של Tinkoff Business — סעיף 'קבלת תשלומים' → 'טרמינלים'. שם גם מגדירים את כתובת ה-webhook ואת רשימת כתובות ה-IP המותרות להודעות. חשוב לציין את NotificationURL — בלעדיו, Tinkoff לא יכול להודיע לשרת שלך על שינויים בסטטוס התשלום, וההזמנות יישארו ללא טיפול.

המעבר ביניהן הוא רק דרך TerminalKey: מפתחות בדיקה מתחילים ב-TinkoffBankTest.

אתחול תשלום

התשלום מאותחל באמצעות שיטת Init. בקשה בסיסית:

$params = [
    'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
    'Amount' => 150000, // в копейках
    'OrderId' => 'order-12345',
    'Description' => 'Заказ #12345',
    'NotificationURL' => 'https://example.com/webhook/tinkoff',
    'SuccessURL' => 'https://example.com/payment/success',
    'FailURL' => 'https://example.com/payment/fail',
];

// Добавляем токен
ksort($params);
$tokenStr = implode('', array_values($params)) . env('TINKOFF_PASSWORD');
$params['Token'] = hash('sha256', $tokenStr);

$response = Http::post('https://securepay.tinkoff.ru/v2/Init', $params);
$paymentUrl = $response->json('PaymentURL');

נקודה חשובה עם הטוקן: הוא מחושב על ידי שרשור לפי סדר אלפביתי של הערכים (לא המפתחות) בתוספת הסיסמה. שגיאות ביצירת הטוקן הן הבעיה הנפוצה ביותר במהלך האינטגרציה. לאחר קבלת PaymentURL, הקונה מופנה לדף של Tinkoff. כל ממשק התשלום נמצא בצד שלהם.

אם ברצונך להקים שער תשלומים מאפס או לשדרג אחד קיים, צור קשר לייעוץ.

הוראות שלב אחר שלב

1. קבל TerminalKey ו-Password בחשבון האישי של Tinkoff.
2. ציין את NotificationURL ואת רשימת כתובות ה-IP עבור ה-webhook.
3. הטמע אתחול תשלום באמצעות Init עם טוקן נכון.
4. הגדר מטפל ב-webhook לקבלת הודעות.
5. בדוק את כל התרחישים בסביבת הבדיקות.
6. עבור למפתחות ייצור והתחל בניטור.

כיצד אנו מעבדים הודעות?

לאחר התשלום, Tinkoff שולח POST אל NotificationURL עם נתונים בפורמט $params = [ 'TerminalKey' => env('TINKOFF_TERMINAL_KEY'), 'Amount' => 150000, // в копейках 'OrderId' => 'order-12345', 'Description' => 'Заказ #12345', 'NotificationURL' => 'https://example.com/webhook/tinkoff', 'SuccessURL' => 'https://example.com/payment/success', 'FailURL' => 'https://example.com/payment/fail', ]; // Добавляем токен ksort($params); $tokenStr = implode('', array_values($params)) . env('TINKOFF_PASSWORD'); $params['Token'] = hash('sha256', $tokenStr); $response = Http::post('https://securepay.tinkoff.ru/v2/Init', $params); $paymentUrl = $response->json('PaymentURL'); :

public function handleWebhook(Request $request): JsonResponse {
    $data = $request->all();
    // Проверяем токен
    $received = $data['Token'];
    $checkData = $data;
    unset($checkData['Token']);
    ksort($checkData);
    $expected = hash('sha256', implode('', array_values($checkData)) . env('TINKOFF_PASSWORD'));
    if (!hash_equals($expected, $received)) {
        return response()->json(['error' => 'Invalid token'], 403);
    }
    if ($data['Status'] === 'CONFIRMED') {
        Order::where('id', $data['OrderId'])->update(['status' => 'paid']);
        // отправить чек, запустить логику доставки
    }
    return response()->json(['OK' => true]);
}

סטטוסים שיש לטפל בהם: application/x-www-form-urlencoded, public function handleWebhook(Request $request): JsonResponse { $data = $request->all(); // Проверяем токен $received = $data['Token']; $checkData = $data; unset($checkData['Token']); ksort($checkData); $expected = hash('sha256', implode('', array_values($checkData)) . env('TINKOFF_PASSWORD')); if (!hash_equals($expected, $received)) { return response()->json(['error' => 'Invalid token'], 403); } if ($data['Status'] === 'CONFIRMED') { Order::where('id', $data['OrderId'])->update(['status' => 'paid']); // отправить чек, запустить логику доставки } return response()->json(['OK' => true]); } , AUTHORIZED, CONFIRMED, REJECTED, REFUNDED. הגנה נוספת — בדיקת כתובת ה-IP של השולח: Tinkoff מפרסם את רשימת כתובות ה-IP שלו בתיעוד, ניתן לסנן ברמת nginx או middleware.

פיסקליזציה באמצעות FFD 1.2

אם העסק מחויב להדפיס קבלות (54-FZ), יש להעביר אובייקט Receipt בבקשת Init:

'Receipt' => [ 'Email' => '[email protected]', 'Taxation' => 'usn_income', 'Items' => [ [ 'Name' => 'Товар 1', 'Price' => 100000, // в копейках 'Quantity' => 1.0, 'Amount' => 100000, 'Tax' => 'none', 'PaymentMethod' => 'full_payment', 'PaymentObject' => 'commodity', ], ], ], 

הפיסקליזציה מתבצעת על ידי Tinkoff באופן אוטומטי — אין צורך לחבר קופה רושמת מקוונת משלך. הקבלה נשלחת למייל או לטלפון של הקונה. הפורמט בשימוש הוא FFD 1.2.

למה לבחור במחסנית הזו?

שער התשלומים מעבד עסקאות פי 1.5 מהר יותר מהמתחרים, וזמן תגובת ה-API אינו עולה על 200 אלפיות השנייה. זה קריטי לפרויקטים בעלי עומס גבוה. אנו מגדירים ניטור והתראות על תקלות — תלמד על בעיות לפני שהן משפיעות על המכירות. עלות האינטגרציה קבועה בשלב ההסכם ואינה משתנה במהלך התהליך. עלות האינטגרציה מתחילה מ-€500. הזמן אינטגרציה — קבל שער תשלומים יציב.

החזרים

החזר באמצעות שיטת Cancel:

$params = [
    'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
    'PaymentId' => '12345678',
    'Amount' => 75000, // частичный возврат
];
// добавить Token по той же схеме
Http::post('https://securepay.tinkoff.ru/v2/Cancel', $params);

החזר מלא — העבר Amount השווה לסכום ההזמנה או אל תעביר אותו כלל. אנו מיישמים את שני התרחישים תוך התחשבות בלוגיקה העסקית.

תוצרים והיקף עבודה

לוח זמנים ועלות

האינטגרציה אורכת בין 3 ל-7 ימי עבודה בהתאם למורכבות ולצורך בפיסקליזציה. העלות מחושבת באופן אישי לאחר הערכת היקף העבודה, החל מ-€500. קבל ייעוץ — צור קשר. אנו גם מסייעים בקבלת TerminalKey ובבדיקות בסביבת הבדיקות.